Introduction to i18n for Angular
Tags: angular, internationalization, webdev, templates
Published: 2019-12-08 07:46:28

![France](https://firebasestorage.googleapis.com/v0/b/fluindotio-website-93127.appspot.com/o/posts%2Fintroduction-to-i18n-for-angular%2FIMG_20160830_104245.jpg?alt=media&token=025048f2-a7e2-45a8-97cd-72cabf4dcb95)

*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](https://trello.com/) 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](https://next.angular.io/guide/i18n)  on angular.io.

![Alexander Nevsky Cathedral](https://firebasestorage.googleapis.com/v0/b/fluindotio-website-93127.appspot.com/o/posts%2Fintroduction-to-i18n-for-angular%2FIMG_2685.JPG?alt=media&token=225d3c7b-d5c6-48e9-910f-365691632351)

## Step 1:`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 `span` and a `my-component`. Both are marked for internationalization the same way. Add what looks like an `i18n` attribute. This will be stripped away by the build.

```html
<span i18n>Hello!</span>
<my-component i18n>Goodbye!<my-component>
```

For both of these, the `i18n` markers indicate that the strings within the tags should be translated.


## Step 2:`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">
```

The `i18n-alt` marker indicates that the "alt" attribute should be translated.

## Step 3: Install @angular/localize
Add a dependency on `@angular/localize` 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 [`XLIFF`](https://en.wikipedia.org/wiki/XLIFF).

```shell
ng xi18n
```

x18n refers to 'extract internationalization". This will render a new file located at`src/messages.xlf`. Open this messages file in a translation tool (eg [Virtaal](https://virtaal.translatehouse.org/)) or pass it to a [translation house](https://www.onehourtranslation.com/) for translation.

What you should get back is a translated XLIFF file. Let's imagine I get back a french file and store it at `src/messages.fr.xlf`.

## Step 5: Configure `angular.json`
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* in `angular.json`, add an `i18n` 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 (`en-US`), and the the new language is French (`fr`).

```json
      "i18n": {
          "sourceLocale": "en-US",
          "locales": {
              "fr": "src/messages.fr.xlf"
          }
      }
```

You'll also have to set "localize" to `true` in your `angular.json` configuration options. This belongs, for example, within `angular.json`, look for`/projects/my-project/architect/build/configurations/production/localize`.

```json
              "localize": true
```

## Step 6: Run a build
Based on the newly configured `angular.json` file, every time you run a production build with `ng build --prod`, you'll get two (or more) folders in your `/dist/` 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 `example.org/en-US/` and `example.org/fr/`, or it could be `example.org` and `fr.example.org`.