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:
sync_previewuploadsmessages.jsonas a dry run. It reports the keys the sync would create, the protected tokens and the estimated credits.- You approve the spend.
syncuploads the file and queues the translation. fill_statuspolls until the translation is complete.- You approve the publish.
pullwritesmessages.<locale>.jsonfor each target language intooutput.
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 (localeandtranslationsat the root) and the config saysformat: angular_json. It counts the ids undertranslations. Any otherformatfails, because the server refuses it.targets: eachmessages.<locale>.jsonwas written by apullof 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
meaninganddescriptionof a message, so the translator does not see them. - A running app does not pick up a new publish: rebuild it or reload it.