Интернационализация (i18n)

Интернационализация приложений - это многогранная область разработки, направленная на то, чтобы сделать приложения доступными и удобными для пользователей по всему миру. В этом руководстве описываются инструменты интернационализации Angular (i18n), которые помогут вам сделать ваше приложение доступным на нескольких языках.

Угловой и i18n

Интернационализация - это процесс разработки и подготовки вашего приложения для использования на разных языках. Локализация - это процесс перевода вашего интернационализированного приложения на конкретные языки для определенных языков.

Angular упрощает следующие аспекты интернационализации:

• Отображение дат, чисел, процентов и валют в локальном формате.
• Подготовка текста в шаблонах компонентов для перевода.
• Обработка множественных форм слов.
• Обработка альтернативного текста.

Для локализации вы можете использовать Angular CLI для генерации большей части шаблонов, необходимых для создания файлов для переводчиков, а также для публикации вашего приложения на нескольких языках. После того, как вы настроили свое приложение для использования i18n, интерфейс командной строки может помочь вам выполнить следующие шаги:

• Извлечение локализуемого текста в файл, который вы можете отправить для перевода.
• Создание и обслуживание приложения для заданной локали с использованием переведенного текста.
• Создание многоязычных версий вашего приложения.

Настройка локали вашего приложения

Локаль - это идентификатор (id), который относится к набору пользовательских предпочтений, которые обычно используются в одном регионе мира, например в стране. Этот документ ссылается на идентификатор локали как «локаль» или «идентификатор локали».

Идентификатор локали Unicode состоит из идентификатора языка Unicode и (необязательно) символа - с последующим расширением локали. Например, в идентификаторе локали `fr-CA`` fr` относится к идентификатору французского языка, а `CA` относится к расширению локали Канада.

Angular следует соглашению Unicode LDML, которое использует стабильные идентификаторы (идентификаторы локали Unicode) на основе нормы BCP47. Очень важно следовать этому соглашению при определении вашей локали, потому что инструменты Angular i18n используют этот идентификатор локали, чтобы найти правильные данные соответствующей локали.

По умолчанию Angular использует язык en-US, который является английским, как говорят в Соединенных Штатах Америки.

Идентификаторы локали, используемые CLDR и Angular, основаны на BCP47. Эти спецификации меняются со временем; следующая таблица отображает предыдущие идентификаторы на текущие на момент написания:

трубы i18n

Угловые трубы могут помочь вам с интернационализацией: DatePipe, CurrencyPipe, DecimalPipe и PercentPipe используют данные локали для форматирования данных на основе LOCALE_ID.

По умолчанию Angular содержит данные только для en-US. Если вы установите значение LOCALE_ID для другой локали, вы должны импортировать данные локали для этой новой локали. CLI импортирует данные локали для вас, когда вы используете параметр --configuration с ng serve и ng build.

Если вы хотите импортировать данные локали для других языков, вы можете сделать это вручную, добавив их в файл src / app / app.module.ts

import { registerLocaleData } from '@angular/common';
import localeFr from '@angular/common/locales/fr';
// the second parameter 'fr' is optional
registerLocaleData(localeFr, 'fr');

Демонстрация в реальном времени:

См. Pen src / app / app.module.ts от w3resource ( @ w3resource ) в CodePen .

Первый параметр - это объект, содержащий данные локали, импортированные из @ angular / common / locales. По умолчанию импортированные данные локали регистрируются с идентификатором локали, который определен в самих данных локали Angular. Если вы хотите зарегистрировать импортированные данные локали с другим идентификатором локали, используйте второй параметр, чтобы указать пользовательский идентификатор локали. Например, данные локали Angular определяют идентификатор локали для французского как «fr». Вы можете использовать второй параметр, чтобы связать импортированные данные французской локали с пользовательским идентификатором локали "fr-FR" вместо "fr".

Файлы в @ angular / common / locales содержат большинство нужных вам данных о локалях, но некоторые дополнительные параметры форматирования могут быть доступны только в дополнительном наборе данных, который можно импортировать из @ angular / common / locales / extra. Сообщение об ошибке информирует вас, когда это так

import { registerLocaleData } from '@angular/common';
import localeFr from '@angular/common/locales/fr';
import localeFrExtra from '@angular/common/locales/extra/fr';
registerLocaleData(localeFr, 'fr-FR', localeFrExtra);

Демонстрация в реальном времени:

Смотрите перо qGqxbj от w3resource ( @ w3resource ) на CodePen .

Переводы шаблонов

Процесс перевода шаблона i18n состоит из четырех этапов:

1. Пометьте статические текстовые сообщения в шаблонах компонентов для перевода.
2. Создайте файл перевода: используйте команду Angular CLI xi18n, чтобы извлечь выделенный текст в стандартный исходный файл перевода.
3. Отредактируйте сгенерированный файл перевода: переведите извлеченный текст на целевой язык.
4. Объедините законченный файл перевода в приложение. Для этого используйте команду сборки Angular CLI, чтобы скомпилировать приложение, выбрав конфигурацию для конкретной локали или указав следующие параметры команды.
• --i18nFile = путь к файлу перевода
• --i18nFormat = формат файла перевода
• --i18nLocale = идентификатор локали

Команда заменяет исходные сообщения переведенным текстом и создает новую версию приложения на целевом языке.

Вам необходимо создать и развернуть отдельную версию приложения для каждого поддерживаемого языка.

Пометить текст атрибутом i18n

Атрибут Angular i18n отмечает переводимый контент. Поместите его в каждый тег элемента, чей фиксированный текст должен быть переведен.

В приведенном ниже примере тег <h1> отображает простое приветствие на английском языке «Hello i18n!» записано в файле src / app / app.component.html

```<h1>Hello i18n!</h1>```

Чтобы отметить приветствие для перевода, добавьте атрибут i18n в тег <h1>.

```<h1 i18n>Hello i18n!</h1>```

i18n - это пользовательский атрибут, распознаваемый инструментами и компиляторами Angular. После перевода компилятор удаляет его. Это не угловая директива.

Помогите переводчику с описанием и значением

Для точного перевода текстового сообщения переводчику может потребоваться дополнительная информация или контекст.

Вы можете добавить описание текстового сообщения в качестве значения атрибута i18n, как показано в примере ниже:

<h1 i18n="An introduction header for this sample">Hello i18n!</h1>
    

Переводчику также может понадобиться узнать значение или намерение текстового сообщения в этом конкретном контексте приложения.

Вы добавляете контекст, начиная значение атрибута i18n со значения и отделяя его от описания с помощью | символ: <значение> | <описание>

<h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1> 

Все вхождения текстового сообщения, имеющие одинаковое значение, будут иметь одинаковый перевод. Текстовое сообщение, связанное с разными значениями, может иметь разные переводы.

Инструмент извлечения углов сохраняет как значение, так и описание в исходном файле перевода, чтобы упростить контекстно-специфические переводы, но только комбинация значения и текстового сообщения используются для генерации конкретного идентификатора перевода. Если у вас есть два одинаковых текстовых сообщения с разными значениями, они извлекаются отдельно. Если у вас есть два одинаковых текстовых сообщения с разными описаниями (не разными значениями), то они извлекаются только один раз.

Установите пользовательский идентификатор для сохранения и обслуживания

Инструмент извлечения угловых i18n создает файл с записью единицы перевода для каждого атрибута i18n в шаблоне. По умолчанию он присваивает каждой единице перевода уникальный идентификатор, такой как этот:

<trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html"> 

Когда вы изменяете переводимый текст, инструмент извлечения генерирует новый идентификатор для этой единицы перевода. Затем вы должны обновить файл перевода с новым идентификатором.

Кроме того, вы можете указать пользовательский идентификатор в атрибуте i18n, используя префикс @@. В приведенном ниже примере определяется пользовательский идентификатор введенный заголовок:

<h1 i18n="@@introductionHeader">Hello i18n!</h1> 

При указании пользовательского идентификатора инструмент извлечения и компилятор генерируют модуль перевода с этим пользовательским идентификатором.

<trans-unit id="introductionHeader" datatype="html"> 

Пользовательский идентификатор является постоянным. Инструмент извлечения не меняет его при изменении переводимого текста. Поэтому вам не нужно обновлять перевод. Такой подход облегчает обслуживание.

Используйте пользовательский идентификатор с описанием

Пользовательский идентификатор можно использовать в сочетании с описанием, включив оба в значение атрибута i18n. В приведенном ниже примере значение атрибута i18n включает описание, за которым следует пользовательский идентификатор:

<h1 i18n="An introduction header for this [email protected]@introductionHeader">Hello i18n!</h1> 

Вы также можете добавить значение, как показано в этом примере:

<h1 i18n="site header|An introduction header for this [email protected]@introductionHeader">Hello i18n!</h1> 

Определите уникальные пользовательские идентификаторы

Не забудьте определить пользовательские идентификаторы, которые являются уникальными. Если вы используете один и тот же идентификатор для двух разных текстовых сообщений, извлекается только первое, и вместо обоих исходных текстовых сообщений используется его перевод.

В приведенном ниже примере пользовательский идентификатор myId используется для двух разных сообщений:

<h3 i18n="@@myId">Hello</h3> 
<p i18n="@@myId">Good  bye</p>

Рассмотрим этот перевод на французский:

<trans-unit id="myId" datatype="html"> 
<source>Hello</source> 	
<target state="new">Bonjour</target> 
</trans-unit>

Поскольку пользовательский идентификатор одинаков, оба элемента в результирующем переводе содержат один и тот же текст, Bonjour:

<h3>Bonjour</h3> 
<p>Bonjour</p> 

Перевести текст без создания элемента

Если есть раздел текста, который вы хотели бы перевести, вы можете заключить его в тег <span>. Однако, если вы не хотите создавать новый элемент DOM просто для облегчения перевода, вы можете заключить текст в элемент <ng-container>. <Ng-container> преобразуется в комментарий HTML:

<ng-container i18n>I don't output any element</ng-container> 

Перевести атрибуты

Отображаемый текст иногда предоставляется в качестве значения атрибута, а не содержимого тега. Например, если в вашем шаблоне есть изображение с атрибутом title, необходимо перевести текстовое значение атрибута title.

<img [src]="logo" title="Angular logo"> 

Чтобы пометить атрибут для перевода, добавьте атрибут в форме i18n-x, где x - имя атрибута для перевода. В следующем примере показано, как пометить атрибут title для перевода, добавив атрибут i18n-title в тег img:

<img [src]="logo" i18n-title title="Angular logo" /> 

Эта техника работает для любого атрибута любого элемента. Вы также можете присвоить значение, описание и идентификатор с помощью синтаксиса i18n-x = "<смысл> | <описание> @@ <идентификатор>".

Предыдущий: Рендеринг на стороне сервера (SSR): введение в Angular Universal
Далее: Рабочая область и структура файла проекта