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:

Mark static text for translation. Angular i18n tooling extracts the text into a standard translation source file. A translator (or ourselves in this demo) edit that file and return the text in the targeted language. 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