Как использовать Angular i18n со встроенным @angular/localize и XLF
В Angular у вас есть пакет @angular/localize, который является собственным встроенным инструментом Angular для переводов. В большинстве случаев этого будет достаточно, это займет несколько шагов, но им легко пользоваться.
Переводы выполняются путем компиляции `aot`, все переводы компилируются в приложение заранее (при создании вашего проекта). Преимущество в том, что у вас есть несколько сборок вашего приложения, которые позволяют использовать разные стратегии для их обслуживания, и, что самое главное, оно имеет отличную производительность. Недостатком является то, что он не оптимизирован для динамической логики, что возможно, и я расскажу об этом в следующей статье.
1. Давайте начнем! Добавьте пакет локализации
Предполагая, что у вас уже есть проект Angular, давайте начнем с добавления пакета локализации в проект. Если вы не следовали Инструкциям по установке Angular и запустили ng new your-project-name для нового проекта (вы можете заменить имя проекта на свое, без пробелов)
Интерфейс командной строки Angular делает эту работу очень простой:
ng add @angular/localize
Обязательно используйте последнюю версию Angular и CLI, это значительно упростит работу.
2. Начать отмечать переводы
Перевод компонентов выполняется путем добавления атрибутов `i18n` к элементам. Это может быть практически любой элемент, напр. блочные элементы, такие как `h1` и `p`, даже встроенные элементы, такие как `span`.
Format:
<element i18n=”{meaning}|{description}@@{id}”>Your text</element>
Example:
<h1 i18n=”{auth login headline|A warm welcome for the login screen@@authLoginHeadline”>Welcome!</h1>
В примере вы видите элемент `i18n` со значением, это значение состоит из трех разделов:
- смысл: предоставить информацию о значении и намерении
- описание: возможность добавления контекста или дополнительной информации
- id: уникальный идентификатор
Все части являются необязательными. Даже идентификатор, если вы не добавите его самостоятельно, будет генерироваться каждый раз, когда вы экспортируете исходные файлы перевода на более позднем этапе. Они будут меняться каждый раз, когда вы будете это делать, поэтому поддерживать ваши переводы будет немного сложнее.
Лучше всего делать это на элементах, которые оборачивают текст. Так что старайтесь не переводить `div`, содержащий элементы `p`, или `ul`, содержащий элементы `li`.
Совет: вы даже можете использовать элемент `ng-template`, если вам не нужны дополнительные элементы DOM, поэтому вам не нужно использовать элементы `span`, если вам нужно несколько переводов. .
3. Создать исходные файлы перевода
Действительно удовлетворительный шаг в процессах. Заставьте Angular CLI пройтись по всему вашему коду и найти атрибуты `i18n`. Из этого он сгенерирует исходный файл перевода со всеми источниками перевода.
ng extract-i18n — output-path src/locale
Теперь у вас должен быть файл XLF в каталоге `src/locale` со структурой XML.
Совет: используйте скрипты npm
Облегчите себе задачу, не надо об этом помнить. Откройте файл `package.json` и добавьте строку в раздел `scripts`:
“translate”: “ng extract-i18n — output-path src/locale”,
Теперь вы можете просто запустить `npm run translate` или `yarn translate` для того же результата. Это намного проще для будущего себя и членов вашей команды.
4. Переведите свое приложение
Работать с этим файлом XLF довольно сложно из редактора, особенно когда вам нужно позже объединить его с изменениями. Поэтому я сделал инструмент под названием Что?!
- Что открыть?!
- Добавьте исходный файл перевода `src/locale/messages.xlf`
- Переведите приложение на целевой язык
- Нажмите «Загрузить», когда закончите, и сохраните его в `src/locale/messages.[код языка].xlf` (замените код языка кодом вашего языка, например, nl или fr)
Совет. Если у вас есть исходный файл и файл перевода, вы можете перетащить оба. Он автоматически сопоставит файлы, и вы сможете легко продолжить перевод своего приложения. Вы даже можете увидеть, какие источники были изменены, или отфильтровать пустые переводы.
5. Конфигурация Angular
Теперь нам нужно выполнить окончательную настройку, чтобы Angular использовал только что созданные файлы XLF и скомпилировал их в ваш проект в процессе сборки. Откройте `angular.json` в редакторе кода, вы можете найти его в корневой папке вашего проекта.
Сначала нам нужно добавить конфигурацию i18n с основным (исходным) языком, который используется с текстом в ваших компонентах.
Добавьте следующий фрагмент JSON внутрь `your-project-name`, который находится в `projects`, я поместил его между `prefix` и `architect`.
"i18n": {
"sourceLocale": "en-US",
"locales": {
"nl": {
"translation": "src/locale/messages.nl.xlf"
}
}
},
Не забудьте изменить в этом примере `nl`, найденный в имени объекта и имени файла. Измените его на код языка, на который вы только что перевели свое приложение. Вы также можете изменить `sourceLocale`, если вы не использовали английский язык в коде своего приложения.
Теперь вы можете использовать определенные локали внутри процесса сборки, добавьте эту часть в «конфигурации» над «производством» (тот, что внутри «сборки»).
"nl": {
"localize": [
"nl"
]
},
Последнее, что нам нужно настроить, это возможность обслуживать разрабатываемую версию вашего приложения при использовании другого языка. Вы можете сделать это внутри `configurations`, на этот раз в `serve`. Дублируйте конфигурацию «разработка» и переименуйте ее в код языка, который вы хотите использовать. Добавьте `,[lang]` в конце, чтобы он использовал конфигурацию, которую мы создали ранее. Например:
"nl": {
"browserTarget": "project-name:build:development,nl"
},
Если вы скопировали приведенный выше фрагмент, не забудьте заменить `project-name` своим кодом и кодом языка (в обоих местах).
6. Время вечеринки!
Теперь мы сгенерировали языковые файлы, перевели их и настроили Angular для их использования. Давайте проверим конечный результат!
Производственная сборка
Чтобы создать сборку, вы можете просто использовать ng build или npm run build, как и раньше. Вы заметите небольшую разницу внутри папки `dist`, для каждого языка есть своя сборка.
Обслуживать разработку
Запустите `ng serve — configuration=nl`, чтобы обслуживать ваше приложение, конечно, замените код языка на тот, который вы использовали.
Совет: вы не хотите вводить это каждый раз, по крайней мере, я этого не делаю. Легче создать несколько npm-скриптов внутри `package.json`, как раньше:
“start”: “npm run start:nl”, “start:nl”: “ng serve — configuration=nl”, “start:en”: “ng serve”,
Таким образом, вы можете просто запустить `npm start` или `yarn start` для голландской версии в этом случае или `npm run start:en` (`yarn start:en`) для английской. Намного проще.
Что дальше?
Вот и все, теперь у вас есть многоязычное приложение Angular! С этого момента вы можете продолжить работу над своим приложением, просто повторив шаги 2, 3 и 4. Обязательно пометьте весь текст в новых компонентах и сгенерируйте новые исходные файлы.
Как я упоминал ранее, с таким инструментом, как Что?! вы можете добавить свой новый исходный файл и существующие переводы. Он автоматически объединит их и покажет любые изменения. Вы можете работать с ними и добавлять любые новые переводы. Вам останется только проверить изменения, перевести дополнения и включить результат в свой проект. Вы готовы к сборке и запуску!
Совет. проведите пошаговое руководство или PR-обзор, чтобы убедиться, что весь текст проходит процесс перевода.
Вот оно!
Это все, что вам нужно для начала работы с модулем Angular i18n, есть еще много чего рассказать. Вы можете подписаться на меня в Medium или Twitter для получения новых статей.
Есть вопросы или отзывы? Дайте мне знать в комментариях или напишите мне в Твиттере!
