Continuing, what has become, an Angular2 series on my blog, today I would like to show you, how to internationalise your Angular2 application. You will learn how to tag your messages, how to build xlf files for translation and to configure your application.
- Internationalization (i18n) vs localization (l10n)
- Installing the tools your need
- Generating your app
- Translating app content
- Creating language files
- Making angular use the translation files
Internationalization (i18n) vs localization (l10n)
The first thing I would like to cover is the difference between the terms above. This is an explanation you can find on w3c service:
Localisation refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a “locale”).
Internationalisation is the design and development of a product, application or document content that enables easy localisation for target audiences that vary in culture, region, or language.
In short, we will focus on making your app translatable.
Installing the tools your need
The angular team has prepared a tool, which extracts messages for translation. It is a part of angular compiler CLI. You install it with the angular compiler using following command:
npm install @angular/compiler-cli @angular/platform-server --save.
Generating your app
As I mentioned before in the tutorial and post about Angular CLI, when you starting a new project, in my opinion, you should use the CLI. Unfortunately, right now, you can’t use the CLI in translated applications. It’s because the CLI compiles your templates while doing the build. The problem with that is, the translations are applied during the compilation. This means the CLI would have to generate one build per language… Currently, maintainers of i18n are discussing possibilities, how to merge these two worlds. Until it’s resolved, if you want to translate your application, you have to stick to a traditional approach.
Now, when you have a working project, we’re ready to put some translatable content there.
Translating app content
To mark text for translation, you need to add i18n attribute to the html tag surrounding this text. Look at the examples here:
You can translate tag contents and also values in other attributes (
i18n placeholder). You can also assign a comment to i18n attribute, which will be stored also in the files with all your messages. It also works if you have other tags inside (like with the google link example).
Creating language files
To parse your app and generate messages.xlf file, you need to run the
ng-xi18n tool. It’s located in
node_modules\.bin\ng-xi18n. It analyses all your templates, extracts messages to be translated and creates a messages.xlf file.
The i18n support is still in the beta stage. The
ng-xi18n will probably output some error messages, but your can ignore them.
After a while, messages.xlf file is generated:
Now, you need to move this file to
/src/lang folder, create a copy for every language you want to use. I have created files for English and Polish. The latter looks like this (
messages_pl.xlf). Notice, the translations in the
Making angular use the translation files
Now, all files are setup - we need to let angular know it should use them.
SystemJS plugin to read files text content
Because we will use SystemJS to load xlf files, we need to make it possible to load pure text with it. Create a file
Configuring the application
First, we need to load the text plugin and setup the language to use. The latter can be done using cookies or read from some sort of API. For the purpose of this post, I simply hardcoded it. The code below has to be added to
index.html, before the app initialization.
Next, we need to add a script, which will generate translation providers:
document['locale'], getting a file with translations and passing it in the array with providers.
Now, we have to modify
main.ts file to use these providers:
After these changes, we have an application available in two languages and a possibility to add as many others as you need.
Even though the internationalisation for Angular2 is still in beta, it seems to be working quite well. It’s simple to use and covers pretty much everything you might need. The only downside for me is you can’t use it with projects generated with the CLI tool, but that should be solved soon, I hope.
As always, you can get the code for this post from GitHub.