Angular Localization
Localize an Angular application with Angular's own internationalization: mark the texts with i18n and $localize, extract them into a resource file, translate it in Soluling, and let the Angular CLI build a localized application for each language.
Soluling reads every format the Angular extract tool writes, shows plurals and selects in a pattern editor, checks the placeholders, and writes the localized resource files. Translate in Soluling Desktop or in a browser with Soluling Cloud. This guide uses the Driving sample, a small driving time calculator dialog built with Angular Material.
- Input
- The resource file of
ng extract-i18n: XLIFF 1.2 or 2.0 (.xlf), XMB (.xmb), ARB (.arb), or JSON (.json) - Output
- Localized resource files (
messages.fi.xlf) thatng build --localizecompiles into an application for each language - Runtime
- One build per language, or one build that loads the translations at runtime with Soluling's Angular library
- Cloud
- Upload
messages.xlfto Soluling Cloud directly; no desktop step needed
On this page
- Tutorial: localize an Angular application step by step
- How Angular localization works
- Context: keep translations when texts change
- Load the translations at runtime
- Translate in Soluling Cloud
- Do and don't
- Typical localizability problems
- Troubleshooting
- The Driving sample
- FAQ
Localize an Angular application, step by step
Six steps take the Driving sample from an English-only application to an application for each language.
Prepare: mark the texts in templates and code
Add Angular's localization package with ng add @angular/localize. Then mark every text the user sees:
-
Templates:
i18non the element. Put it on the deepest element that contains one meaningful text, such as apor abutton, not on adivaround several of them. -
Attributes:
i18n-attribute. A plaini18nmarks the element's content only. To localize aplaceholder,title, oralt, addi18n-placeholder,i18n-title, ori18n-alt. -
Code:
$localize. Change"Driving Time"to$localize`Driving Time`with backticks. -
Meanings and comments.
i18n="header|The title of the dialog"gives the text a meaning (before|) and a comment for the translator (after it). Comment every interpolation, such as{name}, so the translator knows what it is. -
Plurals and selects. Use ICU expressions, such as
{hours, plural, one {...} other {...}}, instead of building sentences from pieces. Chain them instead of nesting them; see patterns.
i18n on its inputs, so their placeholders are not localized: a common mistake that a pseudo translation reveals.Extract: create the resource file and a Soluling project
Run Angular's extract tool. It collects the marked texts into one resource file:
ng extract-i18n --format=xlf2 --output-path src/locale
Soluling supports every format: XLIFF 2.0 (xlf2), XLIFF 1.2 (xlf), XMB (the localized files are .xtb), ARB, and JSON. Use JSON if you load the translations at runtime; JSON doesn't contain meanings or comments.
Drag and drop messages.xlf on Soluling. Project Wizard starts. Choose the Context method, how Soluling identifies each text (see context), add the target languages, and click Finish.
Translate: texts, placeholders, and plural patterns
Each extracted text is a row in the grid, with its meaning, comment, and location for context. Interpolations such as {{hours}} and HTML elements inside a text are placeholders: the translator moves them but doesn't change them. Plurals and selects open in the pattern editor, which shows the plural forms that each target language needs, such as one and other in Finnish and only other in Japanese.
- Machine translation and translation memory. Click Use Machine Translation to translate with Amazon, Claude, DeepL, Google, Microsoft, ModernMT, or MyMemory, and reuse earlier translations from translation memory and terminology.
- External translators. Send a translation package, an Excel file, or XLIFF to a translator, and import the results back. See teamwork.
- Translators in a browser. Upload the project to Soluling Cloud and let translators work in Translate.
Check: find problems before release
Pseudo translation. Click Translate | Pseudo Translations | Fill, build, and run the application. Pseudo translations use accented characters, so strings still in the code (shown in plain English) stand out. See pseudo translation.
Pseudo-translated build
Validation. Soluling validates translations while you type and in batch (Validation | Validate Translations): missing translations, inconsistent placeholders and patterns, duplicate hotkeys, and more. See validation.
Validation
Build: create the localized resource files and applications
Choose Home | Build All. Soluling writes a localized resource file for each language next to the original, such as src\locale\messages.fi.xlf. Add them to angular.json, and build:
"i18n": {
"sourceLocale": "en-US",
"locales": {
"fi": "src/locale/messages.fi.xlf",
"de": "src/locale/messages.de.xlf",
"ja": "src/locale/messages.ja.xlf"
}
}
ng build --localize
The CLI compiles a complete application for each language into its own folder. Deploy each folder to its own URL, such as /fi/. To serve one language while developing, add a build configuration with "localize": ["fi"] and run ng serve -c=fi.
dist\Driving.Update: translate only what changed
When the application changes, run ng extract-i18n again and click Home | Scan. Soluling compares the new resource file with the project, keeps the existing translations, adds the new texts, and marks the rows whose original text changed. Translate the new rows, build, and run ng build --localize. Add the extract, scan, and build steps to your build pipeline with SoluMake or, with Soluling Cloud, SoluCLI.
The translations are compiled into the application
The i18n attributes are used only by Angular's tools; the browser never sees them. When you build with --localize, the compiler replaces every marked text and $localize string with its translation from the resource file of the language and writes a separate application for each language. So there is one build, one deployment, and one URL for each language, and no translation work at runtime.
If the resource file of a language has no translation for a text, Angular uses the original text. Angular has no other fallback, but Soluling can fill in the missing translations from a fallback language when it builds. See the Samples\Angular\Fallback sample.
Context: keep translations when texts change
The extract tool gives each text an ID calculated from the text. If you fix a typo, the ID changes, and the translation no longer matches. If the same text appears twice, the tool extracts it once, so it can have only one translation. Choose how Soluling identifies the texts with the Context method:
| Context method | How it works | Use it when |
|---|---|---|
| Extract tool ID | The ID that the extract tool generates, or your own ID with i18n="@@myId" |
You set your own IDs, which must be unique in the whole application |
| Original text | The text itself | Your texts are unique and rarely change |
| Meaning value | The meaning and the location, such as i18n="header|" |
You give your texts meanings; a meaning needs to be unique only within its file |
Remember the |: without it, the value is a comment, not a meaning.
Load the translations at runtime
A build for each language means a deployment and a URL for each language. With Soluling's Angular library, one build can serve every language: it loads the translations of the browser's language before the application starts. Install it with npm install @soluling/angular, and load the translations in main.ts:
import { loadTranslations } from '@angular/localize';
import { getTranslations } from '@soluling/angular';
getTranslations('assets/i18n').then(translations =>
{
if (translations)
loadTranslations(translations);
import('./app/app.module').then(module =>
platformBrowserDynamic().bootstrapModule(module.AppModule));
});
The translations are JSON resource files named by language, such as assets/i18n/fi.json; extract with --format=json, and Soluling builds them. To change the language, the application loads the page again with the new language. See the Samples\Angular\Runtime sample.
Translate in Soluling Cloud
With Soluling Cloud, translators use Translate in a browser. How you start depends on what you localize:
- Angular resource files (
.xlf,.xmb). On the dashboard, add a project, selectmessages.xlf, and choose Angular resource file as the source type and the context. Translators work in Translate; click Build localized files and downloadmessages.fi.xlfand the others. When the application changes, upload the newmessages.xlf; the existing translations are kept. No desktop step is needed. - Projects with several resource files or Soluling Desktop settings. Create the project in Soluling Desktop, and choose Translate | Configure Cloud to upload it. Use Import from Cloud to get the translations back and build the localized files locally. Your application files never leave your machine.
To run the scan, upload, import, and build steps in your build pipeline, use SoluMake. See the Cloud tutorial and workflows.
Do and don't
Do
- Mark attributes with
i18n-placeholder,i18n-title, and so on. - Use
$localizefor every text in code, including page titles. - Give texts meanings, or your own IDs, so that translations survive text changes.
- Comment every interpolation, such as
{name}. - Use ICU plural and select expressions, chained rather than nested.
- Pseudo-translate before the first real translation.
Don't
- Put
i18non a container with several texts. - Build sentences from pieces in the template or code.
- Nest plural and select expressions; Soluling's pattern editor can't edit them.
- Forget the
|after a meaning; it becomes a comment. - Edit the extracted
messages.xlfby hand; extract it again.
Typical localizability problems
See also internationalization and pseudo translation.
| Problem | How it shows | Find and fix |
|---|---|---|
| Unmarked attributes | Placeholders and tooltips in English in a pseudo-translated build | Add i18n-placeholder or the matching i18n-attribute. |
| Strings in code | Page titles and messages in English | Use $localize. |
| Sentences built from pieces | Word order and plurals are wrong in the translation | Use one text with interpolations, or an ICU plural expression. |
| Translations lost after a text change | Rows come back untranslated after a typo fix | Use meanings or your own IDs, and the matching context method. |
| One translation for two meanings | The same text needs different translations in different places | Give the texts different meanings. |
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| A text is missing from the resource file | It is not marked, or only its content is marked | Add i18n, i18n-attribute, or $localize, and extract again. |
| The build fails with missing or invalid translations | The localized file does not match the current messages.xlf |
Extract, scan, and build in Soluling again before ng build --localize. |
| Translations disappear after extracting again | The extract tool IDs changed with the texts | Use meanings or your own IDs, and set the context method. |
| A JSON file has no comments or meanings | Angular's JSON format doesn't contain them | Use XLIFF for translation, and JSON only for runtime loading. |
| The pattern editor doesn't open | The plural or select expressions are nested | Chain the expressions instead of nesting them. |
The Driving sample
The sample is in Samples\Angular\Driving of the Soluling installation and on GitHub. It is an Angular Material dialog with a Finnish translation, and Soluling projects for each resource format: XLIFF 2.0 and 1.2, XMB, ARB, and JSON. The Samples\Angular folder has more samples:
- Simple: a localized Angular application. Try this first.
- Runtime: one build that loads the translations at runtime.
- Patterns: plurals, genders, selects, and chained patterns.
- Ids: the ways to give the texts their context.
- Fallback: fallback languages.
See Angular localization in the Desktop documentation for all the details.
FAQ
messages.xlf to Soluling Cloud, translate in Translate, and download the localized files. See Translate in Soluling Cloud.Related
- Angular localization - the full Desktop documentation
- Patterns - plurals, genders, and selects
- SoluCLI - Soluling Cloud from your build pipeline
- Supported formats - everything else Soluling localizes