Angular: Introduction to Internationalization (i18n)

How to easily add other languages to your Angular project

A few weeks ago, in one of the many conversations that I have with Martin McWhorter at work (super cool guy I have the pleasure of working with, who also happens to know a lot about Angular), we started discussing internationalization in Angular using angular-cli and I decided that it was a great topic for my next article.

Dealing with internationalization is a key aspect when building worldwide applications and most developers have to deal with it sooner or later.

Angular provides us with a set of built-in functionalities to deal with internationalization (i18n) — thank you Angular!

• Displaying dates, numbers, percentages in local formats.
• Translating text in component templates.
• Handling plural forms of words.
• Handling alternative text.

We’re going to go through the first two of these in the application that we are going to write in this article. Then we’re going to discuss a couple of other topics related to internationalization in an Angular app.

By default, Angular uses the locale en-US. To set your application locale to another value use the CLI parameter locale with the proper value that you want to use (note that angular follows the Unicode LDML convention).

ng serve --aot --locale es

For example, the command above would serve your application setting the locale to Spanish. You can use the locale parameter with ng-serve and with ng-build.

Let’s Start Coding

As I stated earlier, we’re going to go through some of the key features that Angular provides to handle internationalization. We’re going to be using angular CLI to create and run the application with AOT compiler (setting and configuring the internationalization for JIT is not part of this article. Go to the angular documentation for information about internationalization with the JIT compiler).

The idea is to create an application that can be built and run with locale set in Spanish or, by default, in English.

First of all, let’s create the application. Install Angular CLI if you don’t have it yet. Then open your favorite console, go to the folder that you are going to use and run the CLI command to create a new project: ng new internationalization.

Then install all packages using npm install (this should have already been executed but just in case, let’s do it again) and run the application using ng serve to check that everything is working ok.

By default, Angular serves the application with the locale set to en-US, so let’s use that as our default as well. To run the application in Spanish, let’s just add an entry to the package.json scripts section: "start:es": "ng serve --aot --locale es",

Using i18n pipes

Angular has a built-in set of pipes to deal with some internationalization issues like dates, decimals, and percentages.

Let’s use datePipe as an example:

<div style=”text-align:center”>
   <span>{{ dateTime | date: ‘long’ }}</span>
</div>

In app.component.html let’s just add a datePipe to show a dateTime property of our component. We’re going to pass the long property to the pipe to show the long string version of a date.

export class AppComponent {
 title = ‘Angular Internationlization’;
 dateTime = new Date();

In the app component, let’s just set dateTime to a new date.

If we run the application now with npm start we are going to see the en-US version of a long date:

Let’s run it now with the command npm run start:es. Now we’ll see the Spanish version of the date rendered.

Template translations

So this is the main course of our menu — the ability to translate text contained into our templates.

Angular i18n template translation has four phases:

1. Mark static text for translation.
2. Angular i18n tooling extracts the text into a standard translation source file.
3. A translator (or ourselves in this demo) edit that file and return the text in the targeted language.
4. The angular compiler uses the translated file to generate a new version of the application with the targeted language.

Let’s go through each of the phases with examples.

Mark static text using angular i18n

We are going to use the angular i18n attribute with a custom id, by doing this every translation unit generated by the i18n extractor tool is more readable and easy to maintain. We are also going to add a description and a meaning to the i18n attribute, this helps angular to improve the accuracy of the translation.

The image above shows how to use these three values in the i18n attribute. First the meaning then a pipe followed with the description. Finally, prefixed with a double at sign the id.

Let’s create a couple of examples in our application:

Great! In the code above we added two examples to our app.component template. One for the app title and one for the home title. We provided a meaning and a description for both.

Use angular i18n tool to extract the text into a file

Now we’re going to run the command ng xi18n from angular cli to generate the main translation file. This file is going to generate our base translation file, called messages.xlf in our src folder (you can pass another location and/or name as params to the command).

Now that we have our base translation file, we have to create the new language-specific translation files. First, create a folder “locale” under our src folder, where is where our language specific files are going to live.

Let’s copy the recently generated messages.xlf file into the locale folder and rename it to messages.es.xlf (in our case we are going to have only one file for the Spanish translation).

Edit this new file with the Spanish translation

In a real application, your company would probably hire a translator who provides the translated version of the files (the description and meaning are going to help this person to get a more accurate translation). In this example, we’re going to do it ourselves.

To do this we need to add a <target> tag after each of the <source> tags in the file. Then we type the Spanish version of the text in the target tag.

Great — now we have our Spanish internationalization file ready.

Make angular compile in the specified language

We want to be able to build the application in English or in Spanish and we have almost everything set up to get it done.

To get the application in English we just run npm start command to execute an ng serve behind the scenes — so that’s working.

In order to build the application in Spanish we just have to add a couple of params to the Spanish build script in the package.json file:

The first new param is i18nFile that points to the location of the Spanish translation file. The second param that we are adding is i18nFormat, which refers to the format of the translation file.

Now when we run the command npm run start:es we’re going to build our application with Spanish translation!

Serving the application

In our example, we should have two separate application packages, one with the default language (English) and one in Spanish. We can use different strategies to serve one or another:

• Server-side language detection.
• Url parameters.

Maintaining the translated files

Angular i18n doesn’t provide any functionality to maintain your translated files. But you can use xliffmerge to maintain and merge your xlfs files. Here’s a guide to using it in an angular environment.

Great! Let’s See What We’ve Done

• Configured Angular to compile with a different locale.
• Used Angular built-in pipes to help us with internationalization.
• Used i18n attributes to provided Angular with the information needed for text translation.
• Generated a base translation file.
• Created language-specific files.
• Configured angular to be able to compile the proper language-specific file.
• Pointed out the strategies to serve the correct application package.
• Pointed out how to maintain the translated files.

I hope this piece has helped you understand a little bit more about internationalization with angular!

Here’s the GitHub repo.