angular-cli/docs/documentation/stories/internationalization.md

Documentation below is for CLI version 6 and we no longer accept PRs to improve this. For version 7 see here.

Internationalization (i18n)

If you are working on internationalization, the CLI can help you with the following steps:

• extraction
• serve
• build

The first thing that you have to do is to setup your application to use i18n. To do that you can follow the cookbook on angular.io.

Extraction

When your app is ready, you can extract the strings to translate from your templates with the ng xi18n command.

By default it will create a file named messages.xlf in your src folder. You can use parameters from the xi18n command to change the format, the name, the location and the source locale of the extracted file.

For example to create a file in the src/locale folder you would use:

ng xi18n --output-path src/locale

Building and serving

Now that you have generated a messages bundle source file, you can translate it. Let's say that your file containing the french translations is named messages.fr.xlf and is located in the src/locale folder.

If you want to use it when you serve your application you can use the 4 following options:

• i18nFile Localization file to use for i18n.
• i18nFormat Format of the localization file specified with --i18n-file.
• i18nLocale Locale to use for i18n.
• i18nMissingTranslation Defines the strategy to use for missing i18n translations.

In our case we can load the french translations with the following configuration:

"architect": {
  "build": {
    "builder": "@angular-devkit/build-angular:browser",
    "options": { ... },
    "configurations": {
      "fr": {
        "aot": true,
        "outputPath": "dist/my-project-fr/",
        "i18nFile": "src/locale/messages.fr.xlf",
        "i18nFormat": "xlf",
        "i18nLocale": "fr",
        "i18nMissingTranslation": "error",
      }
// ...
"serve": {
  "builder": "@angular-devkit/build-angular:dev-server",
  "options": {
    "browserTarget": "your-project-name:build"
  },
  "configurations": {
    "production": {
      "browserTarget": "your-project-name:build:production"
    },
    "fr": {
      "browserTarget": "your-project-name:build:fr"
    }
  }
},

To build the application using the French i18n options, use ng build --configuration=fr. To serve, use ng serve --configuration=fr.

Our application is exactly the same but the LOCALE_ID has been provided with "fr", TRANSLATIONS_FORMAT with "xlf" and TRANSLATIONS with the content of messages.fr.xlf. All the strings flagged for i18n have been replaced with their french translations.

Note: this only works for AOT, if you want to use i18n in JIT you will have to update your bootstrap file yourself.

Using multiple languages

When you build your application for a specific locale, it is probably a good idea to change the output path with the outputPath options in order to save the files to a different location.

If you end up serving this specific version from a subdirectory, you can also change the base url used by your application with the baseHref option.

For example if the french version of your application is served from https://myapp.com/fr/ then you would build the french version like this:

"configurations": {
  "fr": {
    "aot": true,
    "outputPath": "dist/my-project-fr/",
    "baseHref": "/fr/",
    "i18nFile": "src/locale/messages.fr.xlf",
    "i18nFormat": "xlf",
    "i18nLocale": "fr",
    "i18nMissingTranslation": "error",
  }

If you need more details about how to create scripts to generate the app in multiple languages and how to setup Apache 2 to serve them from different subdirectories, you can read this great tutorial by Philippe Martin.