This article was written for version 9.0 of Angular or later
English is the most common language for the web, but if you ignore other languages and locales, you're missing out on 80% of the planet
. In my experience at companies like Trello
and Google, I saw first hand that localization (l10n) and internationalization (i18n) can be a competitive advantage.
Supporting customers in other regions by understanding their language and expectations can have great rewards. Every user prefers an application that treats you like a first class citizen?
I18n in Angular
Angular was built with internationalization in mind. There are built-in capabilities for localizing dates, currency, numbers, and more, but part of the magic comes from the declarative templates.
The way you build applications in Angular is to create a tree of components, each with an HTML template. In that template you'll see normal HTML, as well as custom Angular components.
In this intro, I'm going to momentarily ignore pipes and complexities like genders, plurals, and focus on the basics of i18n. There's an awesome full i18n guide
i18n markers in elements
Angular has built-in support for translations and i18n as part of the template syntax.
Let's imagine we have a
. Both are marked for internationalization the same way. Add what looks like an
attribute. This will be stripped away by the build.
For both of these, the
markers indicate that the strings within the tags should be translated.
i18n-X markers in properties/attributes
Similarly we can mark properties/attributes for translation. Let's imagine a simple image.
<img alt="Hello world" i18n-alt src="my-image.jpg">
marker indicates that the "alt" attribute should be translated.
Step 3: Install @angular/localize
Add a dependency on
in your package.json. The version number should match the rest of the Angular framework packages
Step 4: Extract Strings
The CLI has the capability of extracting all of the marked strings into an industry-standard format, such as
x18n refers to 'extract internationalization". This will render a new file located at
. Open this messages file in a translation tool (eg Virtaal
) or pass it to a translation house
What you should get back is a translated XLIFF file. Let's imagine I get back a french file and store it at
Step 5: Configure
As of 9.0 and Ivy, multiple translated builds can be quickly produced as part of the CLI's standard build process. This used to be really slow and somewhat manual.
Within your project key
, add an
key and specify the source locale and locales you would like translated, along with their translated XLIFF file. The original strings in this example were written in English (
), and the the new language is French (
You'll also have to set "localize" to
configuration options. This belongs, for example, within
, look for
Step 6: Run a build
Based on the newly configured
file, every time you run a production build with
ng build --prod
, you'll get two (or more) folders in your
directory, one for each locale and the original locale.
With build-time i18n, there's NO performance overhead at runtime, as each set of static files is entirely dedicated to a single language. Runtime i18n, where messages are loaded as part of application bootstrap, will be made available in the future.
To see your site live, just host each version of the site in a different folder or different domain. This could be
, or it could be