Add i18n to your Angular app

Posted on: 23-2-2024

Create a new Angular project

Create a new project using the Angular CLI:

ng new

We will use the default base project generated by the CLI as a starting point.

Add Localize dependency

Add the angular localize dependency to your project by using the following command:

ng add @angular/localize

Set default language

Choose and set the default language of your app. This is the language in which you will write your code and templates.

Add the following to your angular.json file under the key "projects.<project-name>":

{
    ...,
    "projects": {
        "my-project": {
            "i18n": {
                "sourceLocale": "en-US"
            },
        }
    },
    ...
}

This will make english the default language of your application.

Write templates which use i18n

Navigate to app.component.html and edit the h1 and p tags:

<h1 i18n="@@app.title">Hello, Add i18n to your Angular app</h1>
<p i18n="@@app.text">Congratulations! Your app is running. 🎉</p>

With @@ you can give an ID (identifier) to the text you are translating. This is useful as it will allow you to understand the context of the text when it is written to message.json (as you will see later on in this guide).

I like to use the following naming convention for ID's. <component-name + logical description>

e.g. app.title

This makes it that the chances of having duplicate ID's is low and it will allow you to understand to which component the text belongs to.

Generate source file

Use the following command to extract all text you marked for internationalization:

ng extract-i18n --format=json --output-path=src/locale

This will place the source file named messages.json inside the folder src/locale. It also uses the json format instead of xlf.

Create a Dutch translation file

Copy the generated src/locale/messages.json file and call this new file src/locale/messages.nl.json

Add the following translations to this file:

{
  "locale": "nl-NL",
  "translations": {
    "app.title": "Hallo, {$INTERPOLATION}",
    "app.text": "Gefeliciteerd! Je app draait. 🎉"
  }
}

Now you can see why giving ID's is a good idea. We can instantly tell that the first key is the title of the app component.

Build your app in Dutch and English

Add the following to your angular.json file to make sure that angular knows where to find the supported translations for the project:

  "projects": {
    "my-project": {
      "i18n": {
        "sourceLocale": "en-US",
        "locales": {
          "nl": {
            "translation": "src/locale/messages.nl.json"
          }
        }
      },
    }
  }

Add the following to your angular.json so that angular builds all provided locales:

"architect": {
    "build": {
      "builder": "@angular-devkit/build-angular:application",
      "options": {
        "localize": true,
        ...

run

ng build

This will create a dist folder containing all supported locale versions of your app (dutch and english). If you open dist/my-project/browser/nl/main.js and search for "Gefeliciteerd", you get a hit!

Serve one locale

If you want to serve the dutch version of your app during development, add the following config to "architect.build.configurations":

"nl": {
  "localize": ["nl"]
}

And add this to "architect.serve.configurations":

"nl": {
  "buildTarget": "my-project:build:development,nl"
}

where my-project is the name of your project.

Run the app

ng serve --configuration=nl --open

And voila the website is in dutch now.

Links

https://angular.io/guide/i18n-overview