Angular built-in i18n

Table of contents

• Benefits
• How does it work?
• Deploy multiple locales
• Demo
  • Mark text for translation
  • Extract translatable text
  • Add translations
  • Update build configuration

Benefits

• native support by the Angular team
• ICU expressions support
• ability to validate translations during CI/CD
• integration with built-in pipes (date, currency, etc.)
• smaller bundle size - translations are part of a code
• support for markup in translation (as a translation token)
  • throws an error in case of unexpected markup placeholders
  • directly used tags in the translation will be securely escaped
  • the markup is part of the template, so it's available for binding
• flexibility
  • separate bundle for each locale
  • or single bundle with run-time translation
  • or even dynamic locale change (with some conventions)
• translator-friendly
  • supports meta-data for translation
  • supports different file formats (.arb, .json, .xliff 1.2, .xliff 2.0, .xmb)
  • translations can be split into several files, even with different formats

How does it work?

• mark text for translation in a template via i18n or i18n-* attributes
• mark text for translation in a component via $localize tagged template
• marked text will be replaced with translations during the build
  • or during the bootstrap in case of runtime translation
• LOCALE_ID value and locale data will be applied automatically during the build
  • or should be done manually for runtime translation

Deploy multiple locales

• after the build, each locale will have a separate instance of the app under the appropriate directory
• deploy them all to your storage(s)
• redirect the user to the proper route based on the Accept-Language header
• routing strategies:
  • subdomain (en.wikipedia.org, uk.wikipedia.org)
  • national domain (angular.cn, angular.jp)
  • path prefix (developer.mozilla.org/en-US/, developer.mozilla.org/es/)

Demo

Mark text for translation:

• in component template
• in component code

More details

Extract translatable text

Add extract-i18n configuration to the angular.json.

E.g.

...
"architect": {
  "extract-i18n": {
    "builder": "@angular-devkit/build-angular:extract-i18n",
    "options": {
      "browserTarget": "app:build",
      "outFile": "locales/en.xlf",
      "format": "xlf2"
    }
  }
}
...

Add extract-i18n script to the package.json.

E.g.

{
  "scripts": {
    "extract-i18n": "ng extract-i18n"
  }
}

Execute the command via npm run extract-i18n.

Then you will have an XLIFF file with the extracted text (e.g. en.xlf).

More details

Update build configuration

• add i18n details (source locale, supported locales and their translations)
• update build options (add localization, report on missing/duplicate translations)
• set-up locale-specific builders (for development)

E.g.

...
"i18n": {
  "sourceLocale": "en",
  "locales": {
    "he": {
      "translation": "locales/he.xlf"
    },
    "uk": {
      "translation": "locales/uk.xlf",
      "baseHref": "/uk/"
    }
  }
},
"architect": {
  "build": {
    "options": {
      "localize": true,
      "i18nMissingTranslation": "error",
      "i18nDuplicateTranslation": "error"
    },
    "configurations": {
      "development": {
        "localize": ["en"]
      },
      "he": {
        "localize": ["he"]
      },
      "uk": {
        "localize": ["uk"]
      }
    }
  }
}
...

More details

Add locale-specific serve scripts to the package.json (for development).

E.g.

{
  "scripts": {
    "start:he": "ng serve -c=he",
    "start:uk": "ng serve -c=uk"
  }
}