To merge finished translations into an Angular app, declare the source locale and a translation file for each target locale in angular.json. Then build with the localize option, or run ng build --localize. The CLI emits one complete application variant per locale, and you deploy each variant at its own path or behind language detection. This guide follows Angular’s merge guide, which was checked against current documentation on 2026-10-05. CLI behavior and supported formats vary by version, so confirm against the version your project uses.
What “merging” means in Angular
Angular localizes at compile time. Merging produces a separate, complete build of the app for each locale, with translations baked in. It is not a runtime language switch inside one generated copy. Two settings work together:
As an Amazon Associate I earn from qualifying purchases.
- The
i18nconfiguration in the workspace maps locale identifiers to translation files. - The
localizebuild option decides which of those configured locales get built.
Whether you are internationalizing (making the app locale-ready) or localizing (supplying locale-specific data and text) is explained in the internationalization overview.
Prerequisites
Add the localize package
Run ng add @angular/localize. If the package is missing during a localized build, the CLI can fail with an error explaining how to enable i18n. See Add the localize package.
#1 Best Overall
Mark text and extract it
Angular recognizes template text marked with i18n, attributes marked with i18n-, and $localize tagged messages in code (Prepare component for translation). Running ng extract-i18n then generates a source-language translation file. Your translators fill in a copy of that file for each target locale. Angular documents XLIFF-family formats, XMB, JSON and ARB, and the merge guide also mentions XTB. Choose whichever format your translation process supports. See Work with translation files.
Step-by-step: merge and build
- Configure locales in
angular.json. Set the source locale and map each target locale ID to its translation file. Angular’s example usesen-USas the source and French (fr) as a target. Each locale entry can also takebaseHrefandsubPathsettings. - Enable
localizein the build options. Usetrueto build every configured locale, an array of locale IDs to build a subset, orfalseto disable locale-specific builds. - Use AOT. Ahead-of-time compilation is required to localize component templates.
- Build. Run
ng build --localize. - Build a single locale when needed. Compose a production configuration with a locale configuration, for example
ng build --configuration=production,fr.
Choosing options
| Decision | Choices | When to use which |
|---|---|---|
| Build breadth | localize: true or an array of IDs |
All locales for releases; a subset to speed up targeted builds. |
| Development vs. production | One locale per ng serve; composed configurations for deployable builds |
The dev server handles only one localized locale at a time, so pick one explicitly for local checks. |
| Missing translations | error, warning (default behavior), ignore |
Use error if incomplete locale files must not ship. |
| Serving strategy | Server-side language detection or locale subdirectories | Depends on your hosting and URL design. |
Fail the build on missing translations
Set i18nMissingTranslation to error in your build options. Any message without a translation then stops the build instead of silently falling back to the source text. With warning, the build completes but reports the gaps. ignore suppresses them.
What the build produces
The CLI writes each locale into its own directory beneath the output path. It sets the HTML lang attribute and adjusts the base href for each variant. Because each variant assumes its own base path, your server or CDN must route users to the right one. Deploy multiple locales covers the base href behavior and server setups in more detail.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchQuick Recap
Rank #3
Troubleshooting
- Error about enabling i18n:
@angular/localizeis not installed. Runng add @angular/localize. - Text still appears in the source language: the message may be unmarked, missing from the translation file, or the missing-translation level may be hiding the gap. Set it to
errorto surface it. - Component templates not localized: confirm AOT compilation is on.
- Dev server will not show all languages: this is expected. Serve one locale per run.
- Broken assets or routes in a variant: check
baseHrefandsubPathagainst how you deploy.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
