Skip to main content

Angular apps

easyi18n translates an Angular app that uses the framework's own i18n: the i18n attribute in templates, $localize in code and @angular/localize. The file ng extract-i18n writes is the source of truth. You mark text in the templates, extract it, and easyi18n writes the file of every other language. An Angular app that translates with Transloco or ngx-translate uses the web adapter instead.

The Angular adapter needs CLI 1.2.0 or later.

What init sets up​

init with stack: auto selects the Angular stack when package.json depends on @angular/localize and the project has an angular.json. easyi18n init --stack angular names it explicitly. When package.json also depends on Transloco, ngx-translate or i18next, auto stops with ambiguous_stack: run init again with --stack angular or --stack web, whichever one reads your strings.

init writes an easyi18n.yaml like this one:

workspace: acme
project: shop
mode: a
format: angular_json
output: src/locale
source: src/locale/messages.json
sourceRoot: src/locale
sourceLayout: locale-files

source is the file that sync uploads. Write it with the extractor, in its JSON format, into the directory of source:

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

Run it again after you change a template and before each sync. init does not run it. pull writes messages.<locale>.json beside it for each target language, for example src/locale/messages.es.json.

init also prints how the app loads those files. Where @angular/localize is under dependencies (ng add @angular/localize --use-at-runtime), src/main.ts fetches the file of the language and calls loadTranslations before the app starts. Where it is under devDependencies, angular.json lists each locale under i18n and the build sets localize: true, so ng build --localize writes one app per language, such as dist/shop/browser/es/. Add that section after the first pull: the build reads every file it lists and fails while one is missing.

Message ids​

Give each message its own id:

<h1 i18n="@@home.title">Welcome to {{ title }}</h1>
const label = $localize`:@@cart.checkout:Checkout`;

Without an id, Angular uses a digest of the text, a number such as 8639794031277085594. Editing the text changes the digest, so the next sync creates a new key and its translation starts over. doctor warns on the ids check when any message has a digest and lists them.

A plural or select inside a message, such as the plural of You have {count, plural, …} in your cart, becomes a message of its own. Angular derives its id from its text and takes no @@id for it, so doctor leaves it out of the warning. Editing the plural still starts its translation over.

A plural or select that is the whole message, such as <span i18n>{count, plural, …}</span>, looks the same in the file, so doctor leaves it out too. It takes an id like any other message: <span i18n="@@cart.count">.

Placeholders​

The extractor writes interpolations and nested expressions as tokens, for example Hello, {$INTERPOLATION}! You have {$ICU} in your cart. Element tags become tokens too, such as {$START_TAG_SPAN}. A plural is a message of its own, {VAR_PLURAL, plural, =0 {no items} other {{INTERPOLATION} items}}.

The translation keeps every token and the plural skeleton as they are; only the text around them changes. sync_preview lists the tokens of the file in protected_tokens, and the fill refuses a translation that drops or renames one.

Translate and publish​

The agent uses the file-first tools, the same ones a web or Xcode project uses:

  1. sync_preview uploads messages.json as a dry run. It reports the keys the sync would create, the protected tokens and the estimated credits.
  2. You approve the spend. sync uploads the file and queues the translation.
  3. fill_status polls until the translation is complete.
  4. You approve the publish.
  5. pull writes messages.<locale>.json for each target language into output.

From a terminal or CI, easyi18n sync runs those steps in one command, and easyi18n pull downloads the published files. Neither command writes messages.json. Rebuild with ng build --localize, or reload an app that loads the files at runtime.

What doctor checks​

  • source: the file exists, is Angular's (locale and translations at the root) and the config says format: angular_json. It counts the ids under translations. Any other format fails, because the server refuses it.
  • targets: each messages.<locale>.json was written by a pull of this checkout.
  • ids: the messages whose id is a digest of their text, apart from plurals and selects, nested in a message or not.

Limits​

  • Only the JSON format of ng extract-i18n. XLIFF 1.2, XLIFF 2.0 and XMB/XTB files are not supported.
  • The JSON format leaves out the meaning and description of a message, so the translator does not see them.
  • A running app does not pick up a new publish: rebuild it or reload it.