Angular's i18n tools

杨旭 bio photo By 杨旭

Angular’s i18n tools

The i18n tools help to assist translation of component template text into multiple languages.

The i18n template translation process has four phases:

  1. Mark static text messages in your component templates for translation.
  2. An angular i18n tool extracts the marked messages into an industry standard translation source file.
  3. A translator edits that file, translating the extracted text messages into the target language, and returns the file to you.
  4. The Angular compiler imports the completed translation files, replaces the original messages with translated text, and generates a new version of the application in the target language.

Mark text with the i18n attribute

The Angular i18n attribute is a marker for translatable content. Place it on every element tag whose fixed text should be translated. i18n is not an Angular directive. It’s a custom attribute, recognized by Angular tools and compilers. After translation, the compiler removes it.

<h1 i18n>Hello i18n!</h1>

Help the translator with a description and intent

Separating intent and description with | character. When the same message appears in different places with different intents, they should have different translation.

<h1 i18n="meaning | description">message</h1>

How to translate a message?

You can wrap the message with a span tag. But for some reasons, we don’t want to create new DOM element.

  • Wrap the message with which will never be renderered.
<ng-container i18n>I don't output any element</ng-container>
  • Wrap the message with a HTML comments
<!--i18n: optional meaning|optional description -->
I don't output any element either
<!--/i18n-->

If want to translate some attribute, use i18n-x

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

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

Handle singular and plural

Different languages have different pluralization rules.

<span i18n>{wolves, plural, =0 {no wolves} =1 {one wolf} =2 {two wolves} other {a wolf pack}}</span>
  • wolves - the property in component, determines the number of walves
  • plural - identifies this as a plural translation type
  • pattern - defines a pluralization pattern

Select among alternative texts

<span i18n>The hero is {gender, select, m {male} f {female}}</span>

Create a translation source file with the ng-xi18n tool

Translate text messages

The ng-xi18n command generates a translation source file in the project root folder named messages.xlf. The next step is to translate the English language template text into the specific language translation files. One approach is to dedicate a folder to localization and store related assets , such as internationalization files, there.

Make a copy of the messages.xlf file, put it in the locale folder and rename it messages.es.xlf for the Spanish language translation. Do the same for each target language.

<trans-unit id="af2ccf4b5dba59616e92cf1531505af02da8f6d2" datatype="html">
  <source>Hello i18n!</source>
  <target>¡Hola i18n!</target>
  <note priority="1" from="description">An introduction header for this sample</note>
  <note priority="1" from="meaning">User welcome</note>
</trans-unit>

Locale ID: https://en.wikipedia.org/wiki/XLIFF zh-CN

Build with Aot Compiler

Pre-build a separate application package for each language. In index.html, you determine which language the user needs and serve the appropriate application package. Add parameters to ngc command:

  • –i18nFile: the path to the translation file.
  • –locale: the name of the locale.
  • –i18nFormat: the format of the localization file.

i18n supports with @angular/cli

Extraction

see: https://github.com/angular/angular-cli/wiki/stories-internationalization#extraction

$ ng xi18n --output-path=src/locale --locale=en --out-file=messages.en-US.xlf

$ ng xi18n --output-path=src/locale --locale=en --out-file=messages.zh-CN.xlf

Serve

$ ng serve --aot --i18n-file src/locale/messages.zh-CN.xlf --locale zh-CN

Build

Build for specific locale:

$ ng build --aot --output-path dist/zh-CN --locale zh-CN --i18n-file src/locale/messages.zh-CN.xlf
$ ng build --aot --output-path dist/en-US --locale en-US --i18n-file src/locale/messages.en-US.xlf

Then serving for specific version with --base-href