ICU Messages in Angular

ICU MessageFormat in Angular

Angular has built-in support for ICU MessageFormat directly in templates. Unlike React, which requires a third-party library, Angular's i18n system natively understands ICU syntax for plural and select expressions.

Basic Usage in Templates

Angular uses a special syntax in templates that maps to ICU MessageFormat:

<p i18n>
  {count, plural,
    =0 {No items}
    =1 {One item}
    other {{{count}} items}
  }
</p>

Note: In Angular templates, variable interpolation uses double curly braces {{count}} (Angular syntax) rather than the ICU {count}. The ICU # placeholder for the matched number also works.

Select for Gender

<p i18n>
  {gender, select,
    male {He}
    female {She}
    other {They}
  } updated the document.
</p>

Nested Expressions

<p i18n>
  {gender, select,
    male {He has {count, plural, =0 {no items} one {one item} other {{{count}} items}}}
    other {They have {count, plural, =0 {no items} one {one item} other {{{count}} items}}}
  }
</p>

The i18n Attribute

Mark elements for translation with the i18n attribute:

<!-- Simple text -->
<h1 i18n="Page title|Title for the main page">Welcome</h1>

<!-- With meaning and description for translators -->
<p i18n="user notification|Shown when user receives a message">
  You have {count, plural, one {# message} other {# messages}}.
</p>

The format is i18n="meaning|description" where meaning disambiguates identical English text that should have different translations, and description provides context.

Extracting Messages

ng extract-i18n --output-path src/locale

This generates an XLIFF file (XML-based translation format) containing all marked messages. Translators work with these XLIFF files.

Build Configuration

Angular compiles separate bundles per locale:

{
  "projects": {
    "app": {
      "i18n": {
        "sourceLocale": "en",
        "locales": {
          "ja": "src/locale/messages.ja.xlf",
          "de": "src/locale/messages.de.xlf"
        }
      }
    }
  }
}

ng build --localize

Pipe-Based Formatting

For dates and numbers outside ICU messages, Angular provides pipes:

{{ price | currency:'USD':'symbol':'1.2-2' }}
{{ eventDate | date:'longDate' }}

These pipes are locale-aware and complement ICU messages.

Limitations

• Angular's built-in i18n is compile-time -- you cannot switch locale at runtime without reloading
• For runtime locale switching, consider @ngx-translate or @ngneat/transloco which also support ICU syntax
• ICU expressions must be direct children of elements marked with i18n