- Введение
- Определение строк перевода
- Общие сведения о ключах переводах
- Приоритет программного кода
- Переводы валидации
- Исключительные случаи
Проект использует штатные возможности локализации Symfony. Языковые строки хранятся в файлах, располагающихся внутри директории 'app/Resources/translations'. В ней должны находиться файлы для каждого языка, поддерживаемого вашим приложением:
/app
/Resources
/ translations
messages.en.xlf
messages.ru.xlf
oauth.en.xlf
oauth.ru.xlfВсе языковые файлы должны являться XLIFF формате. Синтаксис которого, основан на 'xml', пример простого файла перевода
<!-- app/Resources/translations/messages.en.xlf -->
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" target-language="en" datatype="plaintext" original="file.ext">
<body>
<trans-unit id="title_post_list">
<source>title.post_list</source>
<target>Post List</target>
</trans-unit>
</body>
</file>
</xliff>Обратите внимание, файлы перевода могут быть переведены с помощью сторонних средств, например weblate
Структура:
- id - неиспользуемый обязательный параметр;
- source - ключ перевода;
- target - строка на необходимом языке;
Языковые файлы, как и ваши переменные требуют ухода и очевидности коллег, рассмотрим несколько примеров.
Плохо:
<trans-unit id="welcome_to_our_application">
<source>Welcome to our application</source>
<target>Добро пожаловать в наше приложение</target>
</trans-unit>Определение каждой строки с помощью "краткого ключа" приводит к путанице при обращении к ним из шаблонов, по этой причине, лучшим будет использовать несвязанный с содержимым, но понятный ключ, например 'welcome'.
Так же, глядя на сообщение "Добро пожаловать в наше приложение", мы не понимаем, где находится или используется это строка. Необходимо указать больше контекста, например это могут быть 'marketing', 'index', 'block', etc
Лучше:
<trans-unit id="marketing_welcome">
<source>marketing.welcome</source>
<target>Добро пожаловать в наше приложение</target>
</trans-unit>В бедующем может потребоваться добавить в нашу маркетинговую страницу подзаголовок или отдельные элементы, что бы не возвращаться к прошлым переводам, эффективнее будет сразу указывать структуру приложения.
Хорошо:
<trans-unit id="marketing_title_welcome">
<source>marketing.title_welcome</source>
<target>Добро пожаловать в наше приложение</target>
</trans-unit>В ходе работы над переводом текста, может возникнуть желание указать переменную по названию css класса, местоположения или просто сделать короче. Прежде чем, сокращать или изменять название, стоит обратить внимание на некоторые аспекты:
Пойму ли я завтра только по ключу
- Где используется этот перевод?
- К какому свойству или событию он относится?
Вложенность ключей не ограничена, по этому необходимо явно понимать, что ключ может содержать коллекцию элементов:
Плохой ключ:
<source>campaing.category_car</source>
В таком наименовании легко запутаться, по той причине, что проект постоянно обновляется и могут быть добавлены имена ключей, которые будут записаны иначе, например 'campaing.classification_bus' и т.п.
Ключ по лучше:
<source>campaing.category.car</source>
Видя такой ключ в отрыве от контекста, например только 'campaing.category', сложно понять, что в действительности имелось ввиду, одна "категория"?
Хороший ключ:
<source>campaing.categories.car</source>
В действительности хорошему ключу, мало выглядеть читаемым и понятным, он должен быть ещё и однообразным с программным кодом.
Программный код должен иметь наивысший приоритет над влиянием наименования ключа, например, если мы делаем перевод модели "Кампания" и у неё свойство названо 'classification', а в 'html' контекст оперирует к более привычному названию "Категории", приоритет будет иметь программный код.
HTML контекст может меняться в зависимости от целей, SEO специалиста, контент менеджера и т.п. по этому привязываться к нему - плохая идея, привязка к программному коду позволяет провести явную ассоциацию модели с файлами перевода.
Переводы правил валидации всегда должны находиться в файлах 'validators.*.xlf'
Наименование должно происходить следующей схеме:
/campaign (Принадлежность)
/errors (Множество ошибок)
/title (Множество ошибок, у переданного свойства)
- exists (Частный случай)
- invalid (Частный случай)
- min (Частный случай)
- etc
То есть 'campaign.errors.title.exists'.
Свойство всегда должно ассоциироваться с множеством ошибок, это необходимо, потому что в переданном значении для валидации может сработать сразу несколько правил.
В ходе работы, предыдущий пример может не подойди по различным причинам, тогда необходимо следовать таблице:
| Ключ | Использование |
|---|---|
| marketing .paragraph1 | Точка перед перечислением заголовков не даёт ни каких плюсов, но проявляется при копировании |
| _ welcome | Только для слов начинающихся с маленькой буквы, например, "привет" |
| Welcome | Только для функциональных слов, например, "Показать все", "Далее", "Да", "Нет" и т.д |
| Welcome to our application | Только для без выходных значений, например перевод в чужом пакете |