Angular

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.

Try Soluling

Resources XLF messages.xlf Soluling Original (English) Translation (Finnish) Driving Time Driving distance Driving speed Calculate Driving time is icu0 icu1 =0 one hours hour other hours hours one minutes minute other minutes minutes Ajoaika Ajomatka Nopeus Laske Ajoaika on icu0 icu1 =0 one hours tunti other hours tuntia one minutes minuutti other minutes minuuttia The strings in messages.xlf have been translated Localized resources XLF messages.xlf fi messages.fi.xlf de messages.de.xlf ja messages.ja.xlf A localized messages.xlf for each language, compiled by ng build --localize Resources XLF messages.xlf Soluling Original (English) Translation (Finnish) Driving Time Driving distance Driving speed Calculate Driving time is icu0 icu1 =0 one hours hour other hours hours one minutes minute other minutes minutes Ajoaika Ajomatka Nopeus Laske Ajoaika on icu0 icu1 =0 one hours tunti other hours tuntia one minutes minuutti other minutes minuuttia The strings in messages.xlf have been translated Localized resources XLF messages.xlf fi messages.fi.xlf de messages.de.xlf ja messages.ja.xlf A localized messages.xlf for each language, compiled by ng build --localize
Soluling writes the localized resource files; the Angular CLI compiles them into a complete application for each language.
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) that ng build --localize compiles 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.xlf to Soluling Cloud directly; no desktop step needed

On this page

Tutorial

Localize an Angular application, step by step

Six steps take the Driving sample from an English-only application to an application for each language.

01

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:

  1. Templates: i18n on the element. Put it on the deepest element that contains one meaningful text, such as a p or a button, not on a div around several of them.
  2. Attributes: i18n-attribute. A plain i18n marks the element's content only. To localize a placeholder, title, or alt, add i18n-placeholder, i18n-title, or i18n-alt.
  3. Code: $localize. Change "Driving Time" to $localize`Driving Time` with backticks.
  4. 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.
  5. 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.
Marking an attribute and a code string for localization Before, the input has a plain i18n attribute, so its placeholder is not extracted, and the page title is a plain string. After, the input has i18n-placeholder and the title uses $localize. The extracted file has the placeholder and the plural result, with Finnish translations. Before: app.component.ts <input matInput i18n [(ngModel)]="distance" placeholder="Driving distance"> titleService.setTitle("Driving Time Calculator"); ✕ Not extracted; stays English Internationalize After <input matInput i18n-placeholder [(ngModel)]="distance" placeholder="Driving distance"> titleService.setTitle($localize`Driving Time Calculator`); messages.xlf and messages.fi.xlf in Soluling placeholder English Driving distance Finnish Ajomatka hours English {VAR_PLURAL, plural, one {{{hours}} hour } other {{{hours}} hours }} Finnish {VAR_PLURAL, plural, one {{{hours}} tunti } other {{{hours}} tuntia }} ✓ Extracted, translated, and the plural forms of each language
The Driving sample itself has a plain i18n on its inputs, so their placeholders are not localized: a common mistake that a pseudo translation reveals.
02

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.

Extracting and creating the project ng extract-i18n writes messages.xlf, which goes through Project Wizard's Context method page (extract tool ID, original text, or meaning value) and Select Languages page (Finnish, German, Japanese). Extract ng extract-i18n src\locale\messages.xlf Drop on Soluling messages.xlf Angular resource file Context method ○ Extract tool ID ○ Original text ● Meaning value Languages Finnish (fi) German (de) Japanese (ja) Use Meaning value when your i18n attributes have meanings, such as i18n="header|".
03

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.
04

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

[Ðŕîvîñĝ Ţîɱé ___] PS Driving distance 220 Driving speed 88 [Çåļçûļåţé ______________] [Ðŕîvîñĝ ţîɱé îš 2 ĥôûŕš 30 ɱîñûţéš ________] Still English (hard-coded)

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

⚠ Inconsistent format string Driving time is {hours} {minutes} (German) The original has two placeholders; the translation has only one: Fahrzeit: {hours} ⚠ Inconsistent pattern count hours plural (Japanese) Japanese has only the other plural form, but the translation has one and other.
05

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.

Localized resource files and localized applications Soluling writes messages.fi.xlf, messages.de.xlf, and messages.ja.xlf next to messages.xlf in src\locale. ng build --localize writes a complete application for each language into the fi, de, and ja folders of dist\Driving\browser. Soluling: Build All DIR src\locale\ XLF messages.xlf original, from the extract tool XLF messages.fi.xlf XLF messages.de.xlf XLF messages.ja.xlf Angular: ng build --localize DIR dist\Driving\browser\ fi fi\index.html the Finnish application de de\index.html ja ja\index.html
Older Angular versions write the language folders directly under dist\Driving.
06

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.

Reference

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, select messages.xlf, and choose Angular resource file as the source type and the context. Translators work in Translate; click Build localized files and download messages.fi.xlf and the others. When the application changes, upload the new messages.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 $localize for 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 i18n on 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.xlf by 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

XLIFF 2.0 or 1.2 for most projects; Soluling supports XMB/XTB and ARB too. Use JSON only for runtime translation loading, because it doesn't contain meanings or comments.

Yes. Upload messages.xlf to Soluling Cloud, translate in Translate, and download the localized files. See Translate in Soluling Cloud.

With Angular's standard localization, yes. With Soluling's Angular library, one build loads the translations of the browser's language at runtime. See Load the translations at runtime.

The extract tool calculates the ID from the text. Give the texts meanings or your own IDs, and choose the matching context method. See Context.

Yes. Soluling also localizes ngx-translate and angular-translate JSON files, in Soluling Desktop and Soluling Cloud.

Related

All guides