@angular/localize

Build-time and runtime i18n. Provides the $localize tagged-template-literal that the Ivy compiler emits for translatable text, plus the build-time tooling that extracts and applies translations.

Purpose

@angular/localize covers the i18n end-to-end:

• Defines the $localize runtime tag that resolves message IDs to translated strings.
• Provides loadTranslations() for runtime translation loading, and a build-time pipeline that bakes translations into the bundle for AOT-compiled production builds.
• Provides format converters for XLIFF 1.2, XLIFF 2.0, XMB/XTB, and JSON.
• Offers schematics for ng add @angular/localize.

Directory layout

packages/localize/
├── src/
│   ├── utils/             # MessageId, Format helpers, parser/serializer base
│   └── ...
├── tools/
│   └── src/               # ng-extract-i18n-merge, conversion CLIs
├── localize/              # Public localize export ($localize)
├── init/                  # @angular/localize/init runtime setup
├── schematics/            # ng-add schematic
└── public_api.ts

Key abstractions

Type / function	File	What it is
$localize	packages/localize/localize/src/localize.ts	The tagged-template-literal runtime.
loadTranslations()	same	Loads the translation table at app startup.
MessageId, parseMessage	packages/localize/src/utils/	Message-ID derivation matching the compiler's algorithm.
Format translators	packages/localize/tools/src/translate/	XLIFF / XMB serializers.

How i18n flows end-to-end

graph LR
  Source["@Component({...}) with i18n attributes"] --> Compiler["@angular/compiler<br/>(extract messages)"]
  Compiler --> XLIFF["messages.xlf"]
  XLIFF --> Translator["External translation"]
  Translator --> Translated["messages.<lang>.xlf"]
  Translated --> Tools["@angular/localize/tools<br/>convert + merge"]
  Tools --> Bundle["Per-locale built bundle<br/>(or runtime-loaded)"]
  Bundle --> Runtime["$localize resolves<br/>at runtime/build time"]

The Angular CLI's ng extract-i18n calls into this package's tools to produce the XLIFF source files. The CLI's i18n configuration option then drives per-locale builds.

Integration points

• @angular/compiler — emits $localize calls and message metadata.
• @angular/compiler-cli — emits the same calls in AOT output. The compiler-cli's extract_i18n.ts entry point produces the source XLIFF.
• Angular CLI / @angular/build — the build orchestration that runs translation pipelines per locale lives in the CLI repo, but invokes APIs from this package.

Entry points for modification

• A new translation file format: add a parser/serializer pair in packages/localize/tools/src/translate/ and register it.
• A new runtime feature for $localize: extend packages/localize/localize/src/. Be conscious that $localize runs very early in app boot — pure functions only.