Angular’s official internationalization(i18n) support

In the previous blog post series, we have seen how to achieve the internationalization support using ngx-translate library. Please read this post if you didn’t read yet. In this blog post, you will see how to achieve it through Angular’s official i18n tools.  “Internationalization is the process of designing a software application so that it can potentially be adapted to various languages and regions without engineering changes”. Angular uses ngx-i18n tools to support internationalization. The process involves four steps.

  1. Identify the messages: Initially mark the static text messages in your component templates.
  2. Generate standard translation files: Extracts the marked messages into an industry standard translation source file(XLIFF and XMB formats).
  3. Translating the messages: Translating the extracted text messages into the target language by Translator tool.
  4. Complete the translation files: Angular compiler imports the compiled translation files and replace the original text with translation text files. Finally it creates translation files based target language.

The demo example is powered by PrimeNG components and the internationalization support for German and Spanish languages. You can close the Github URL to play with the features.

1.  Identify the messages:

Let’s see how we can identify the messages in different possible ways. 

 i.Mark messages with the i18n attribute:

Angular provides i18n custom directive to identify the messages which needs to be translated. With the help of this attribute, angular compilers and tools can easily find and mark them for translation. The i18n attribute removed by the compiler after translation.

For example, you can just append i18n attribute to the label to make it available for translation,

To make the translation accurately, it is good idea to define meaning and description for the attribute. This helpful to define the particular context of the message while doing translation. Both of these options are optional. Lets define this to span element an example,

The i18n extraction tools identify the above messages (with the help of i18n markers) then generates  translation files with translation units.  The generated id for each unit with a random unique text as follows. 

If you edit generated id then there is more chance of loosing the translations for messages. To avoid these problems, it is good idea to define our custom ids as below.

Note: The i18n attribute format can be defined as meaning | description | id .

Finally the complete translation unit with custom id values would be as follows.But remember that duplicate id creates confusion and generates translation units with same message.

You can also create the translation for messages without creating an element in the DOM. You can achieve this in two possible ways.

  1. Use ng-container tag which is used as placeholder without rendering in the DOM.

   2. Use comments with optional meaning and description

ii. Mark messages with the i18n translation attributes:

In the above section, you have seen how the DOM contents can be translated using i18n attribute. You can also translate element attribute’s text content. For example, title of button element. 

Note: The i18n translation attributes should be in the format as i18n-x where x is the attribute of DOM element.

iii. How to handle Singular and Plural criteria:

Each language has specific pluralization rules. We need to handle this pluralization intelligently in the internationalization implementation. Angular handles this  very elegantly in an easy way.  It handles the text content based on number of elements or cardinality. For instance, the framework rating with different possibilities as an example,

In the above example, first parameter indicates the component property, second parameter used to categorize singular or plural type and third parameter indicates pluralization pattern which consists of category and it’s matching value.

The possible Pluralization categories from Angular include:

  • =0 (or any other number)
  • zero
  • one
  • two
  • few
  • many
  • other

iv. How to handle selection expressions:

Similar to pluralization concept, the text selection with different output possibilities requires a special treatment. The select alternative texts based on user selection would be handled as below

The first parameter indicates the compoent property, second parameter specifies select keyword and third one should be pair of possible value and it’s text representation.

2. Generate standard translation files

Now It is time generate translation files for the defined messages in templates.The ng-xi18n extraction tool  is used to extract the i18n-marked texts into a translation source file in an industry standard formats such as XML Localization Interchange File Format (XLIFF, version 1.2) and XML Message Bundle (XMB).You need to run any one of the below command to generate message.xlf (or xmb) in your project root folder.

For a better convenience, lets define the npm script as below,

Now you can run and generate the translation files easily,

At the end,  you can find message.xlf file in  your project root folder which defines translation units for each message.

3. Translating the messages

The ngx-i18n tool generated the English version of translation file by default. Now we need to create translation messages for specific target language. First we need to create locale folder in the project root folder and copy the message file by appending language code for the extension (for example, messages.de.xlf and messages.es.xlf).

Now you need to open the message translation files and edit the text nodes (especially target nodes).The translation unit with simple i18n attribute and German translation would be as follows,

The same way it handles plurals and select messages which are defined in the translation files. In real world, there will be official translators for message conversion.

4. Complete the translation files

The JIT compiler involves the below steps to reflect the changes in the browser

  1. Determining the language version for the current user and load translation file using text plugin. Configure this in your index.html file.

Because of the SystemJS project setup, we used systemjs-text-plugin.js to read text files in this demo example.

2. Importing the appropriate language translation file as a string constant in SystemJS plugin. Configure this in systemjs-text-plugin.js file.

3. Creating corresponding translation providers to guide the JIT compiler.

 The below Three providers tell the JIT compiler how to translate the template messages for a particular language while compiling the application

The getTranslationProviders() function in the following src/app/i18n-providers.ts creates those providers based on the user’s locale and the corresponding translation file:

4. Bootstrapping the application with providers.

The Angular bootstrapModule() method has a second options parameter that can influence the behavior of the compiler.You’ll create an options object with the translation providers from getTranslationProviders() and pass it to bootstrapModule. Open the src/main.ts and modify the bootstrap code as follows:

The project structure after the entire setup would be as follows

The German version of this demo example appeared as below. Use npm start script to run on your dev server. You can change the locale to ‘es’ in your index.html to see the Spanish version.

The app is now internationalized for English, German and Spanish but we can implement this for many more languages.

Conclusion:

The official angular support for internationalization is improved a lot during the last few months. The support enhanced with pluralization, select and nested expressions. You need follow all the above mentioned steps to make your app with multi language feature to get user experience for multiple regions.

Leave a Reply

Your email address will not be published. Required fields are marked *