Angular i18n is Angular's built-in internationalization system. You mark text in templates with the i18n attribute, extract it into XLIFF translation files with ng extract-i18n, translate those files and build a separate version of the app for each locale. Because it uses XLIFF, an industry-standard translation format, Angular projects fit naturally into professional translation workflows. This guide walks through the setup step by step.
How Angular i18n Works
Angular's approach relies on the @angular/localize package. Translatable text is marked in templates and code, extracted into a source file, translated into one file per language and merged at build time. The official Angular internationalization guide documents every option.
Step 1: Add the Localize Package
Run ng add @angular/localize in your project. This adds the package and the configuration needed for compile-time translation.
Step 2: Mark Text for Translation
- In templates, add the
i18nattribute:<h1 i18n>Welcome back</h1>. - Add meaning and description for translators:
i18n="site header|Welcome message on the dashboard". - Give important messages a custom ID with
@@, for examplei18n="@@dashboardWelcome", so IDs stay stable when text changes. - For attributes, use
i18n-title,i18n-placeholderand similar. - In TypeScript, use the
$localizetagged template.
Step 3: Handle Plurals and Alternatives
Angular uses ICU expressions for plurals and selections, for example {count, plural, =0 {no messages} =1 {one message} other {{{count}} messages}}. Translators then add the plural forms their language needs.
Step 4: Extract Source Text
Run ng extract-i18n. By default, Angular creates a messages.xlf file in XLIFF 1.2 format, with every marked message, its ID, description and location. You can also choose XLIFF 2.0, XMB or JSON output with the --format option.
Step 5: Translate the XLIFF Files
Copy the source file for each locale, for example messages.de.xlf, and add translations as target elements. Doing this in a text editor is risky. A CAT editor that opens XLIFF directly protects IDs and placeholders, applies translation memory and runs QA checks. For background on the format, read what is an XLIFF file.
Step 6: Configure Locales and Build
In angular.json, define the source locale and each target locale with the path to its translation file. Build with localization enabled, and Angular produces a separate, fully translated bundle per locale, served for example under /de/ or /fr/.
Angular i18n vs Runtime Libraries
| @angular/localize | Runtime libraries (e.g. ngx-translate, Transloco) | |
|---|---|---|
| When translations apply | At build time | At runtime |
| File format | XLIFF by default | Usually JSON |
| Language switching | Load a different build | Switch without reload |
| Performance | Very fast, no runtime lookup | Small runtime overhead |
If you use a runtime library with JSON files, see our guide on how to translate a JSON file.
Best Practices
- Always add descriptions so translators understand context.
- Use custom IDs for important strings to avoid losing translations when text changes.
- Never concatenate translated strings in code.
- Plan for text expansion and right-to-left layouts.
- Automate extraction and translation sync in your CI pipeline, as described in continuous localization.
Translate Angular XLIFF Files With WordBeam
WordBeam imports Angular XLIFF files directly, keeps IDs and placeholders protected and lets translators work with translation memory, glossary and AI engines such as DeepL, GPT and Claude. QA checks catch broken placeholders before you export, and GitHub and GitLab integrations on the Studio plan keep translations in sync with your code. Learn more about WordBeam for software localization.
Frequently Asked Questions
What format does Angular i18n use?
XLIFF 1.2 by default, with options for XLIFF 2.0, XMB and JSON.
Can I switch languages at runtime with Angular i18n?
The built-in system creates one build per locale, so switching usually means loading a different URL. Runtime libraries allow switching without reload.
Is Angular i18n better than ngx-translate?
It depends on your needs. The built-in system is fast and uses standard XLIFF; runtime libraries are more flexible for instant language switching.