Prepare component for translation

To prepare your project for translation, complete the following actions.

• Use the i18n attribute to mark text in component templates
• Use the i18n- attribute to mark attribute text strings in component templates
• Use the $localize tagged message string to mark test strings in component code

Mark text in component template

In a component template, the i18n metadata is the value of the i18n attribute.

<element i18n="{i18n_metadata}">{string_to_translate}</element>

Use the i18n attribute to mark a static text message in your component templates for translation. Place it on every element tag that contains fixed text you want to translate.

The i18n attribute is a custom attribute that the Angular tools and compilers recognize.

i18n example

The following <h1> tag displays a simple English language greeting, "Hello i18n!".

<h1>Hello i18n!</h1>

To mark the greeting for translation, add the i18n attribute to the <h1> tag.

<h1 i18n>Hello i18n!</h1>

Translate inline text without HTML element

Use the <ng-container> element to associate a translation behavior for specific text without changing the way text is displayed.

Each HTML element creates a new DOM element. To avoid creating a new DOM element, wrap the text in an <ng-container> element. The following example shows the <ng-container> element transformed into a non-displayed HTML comment.

<ng-container i18n>I don't output any element</ng-container>

Mark element attributes for translations

In a component template, the i18n metadata is the value of the i18n-{attribute_name} attribute.

<element i18n-{attribute_name}="{i18n_metadata}" {attribute_name}="{attribute_value}" />

The attributes of HTML elements include text that should be translated along with the rest of the displayed text in the component template.

Use i18n-{attribute_name} with any attribute of any element and replace {attribute_name} with the name of the attribute. Use the following syntax to assign a meaning, description, and custom ID.

i18n-{attribute_name}="{meaning}|{description}@@{id}"

i18n-title example

To translate the title of an image, review this example. The following example displays an image with a title attribute.

<img [src]="logo" title="Angular logo">

To mark the title attribute for translation, complete the following action.

1. Add the i18n-title attribute

The following example displays how to mark the title attribute on the img tag by adding i18n-title.

<img [src]="logo" i18n-title title="Angular logo" />

Mark text in component code

In component code, the translation source text and the metadata are surrounded by backtick (`) characters.

Use the $localize tagged message string to mark a string in your code for translation.

$localize `string_to_translate`;

The i18n metadata is surrounded by colon (:) characters and prepends the translation source text.

$localize `:{i18n_metadata}:string_to_translate`

Include interpolated text

Include interpolations in a $localize tagged message string.

$localize `string_to_translate ${variable_name}`;

Name the interpolation placeholder

$localize `string_to_translate ${variable_name}:placeholder_name:`;

i18n metadata for translation

{meaning}|{description}@@{custom_id}

The following parameters provide context and additional information to reduce confusion for your translator.

For additional information about custom IDs, see Manage marked text with custom IDs.

Add helpful descriptions and meanings

To translate a text message accurately, provide additional information or context for the translator.

Add a description of the text message as the value of the i18n attribute or $localize tagged message string.

The following example shows the value of the i18n attribute.

<h1 i18n="An introduction header for this sample">Hello i18n!</h1>

The following example shows the value of the $localize tagged message string with a description.

$localize `:An introduction header for this sample:Hello i18n!`;

The translator may also need to know the meaning or intent of the text message within this particular application context, in order to translate it the same way as other text with the same meaning. Start the i18n attribute value with the meaning and separate it from the description with the | character: {meaning}|{description}.

h1 example

For example, you may want to specify that the <h1> tag is a site header that you need translated the same way, whether it is used as a header or referenced in another section of text.

The following example shows how to specify that the <h1> tag must be translated as a header or referenced elsewhere.

<h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1>

The result is any text marked with site header, as the meaning is translated exactly the same way.

The following code example shows the value of the $localize tagged message string with a meaning and a description.

$localize `:site header|An introduction header for this sample:Hello i18n!`;

ICU expressions

ICU expressions help you mark alternate text in component templates to meet conditions. An ICU expression includes a component property, an ICU clause, and the case statements surrounded by open curly brace ({) and close curly brace (}) characters.

{ component_property, icu_clause, case_statements }

The component property defines the variable An ICU clause defines the type of conditional text.

To simplify translation, use International Components for Unicode clauses (ICU clauses) with regular expressions.

The ICU clauses adhere to the ICU Message Format specified in the CLDR pluralization rules.

Mark plurals

Different languages have different pluralization rules that increase the difficulty of translation. Because other locales express cardinality differently, you may need to set pluralization categories that do not align with English. Use the plural clause to mark expressions that may not be meaningful if translated word-for-word.

{ component_property, plural, pluralization_categories }

After the pluralization category, enter the default text (English) surrounded by open curly brace ({) and close curly brace (}) characters.

pluralization_category { }

The following pluralization categories are available for English and may change based on the locale.

If none of the pluralization categories match, Angular uses other to match the standard fallback for a missing category.

other { default_quantity }

For more information about pluralization categories, see Choosing plural category names in the CLDR - Unicode Common Locale Data Repository.

function plural(n: number): number {
  let i = Math.floor(Math.abs(n)), v = n.toString().replace(/^[^.]*\.?/, '').length;
  if (i === 1 && v === 0) return 1;
  return 5;
}

minutes example

If you want to display the following phrase in English, where x is a number.

updated x minutes ago

And you also want to display the following phrases based on the cardinality of x.

updated just now

updated one minute ago

Use HTML markup and interpolations. The following code example shows how to use the plural clause to express the previous three situations in a <span> element.

<span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{minutes}} minutes ago}}</span>

Review the following details in the previous code example.

{{minutes}} is an interpolation.

Mark alternates and nested expressions

The select clause marks choices for alternate text based on your defined string values.

{ component_property, select, selection_categories }

Translate all of the alternates to display alternate text based on the value of a variable.

After the selection category, enter the text (English) surrounded by open curly brace ({) and close curly brace (}) characters.

selection_category { text }

Different locales have different grammatical constructions that increase the difficulty of translation. Use HTML markup. If none of the selection categories match, Angular uses other to match the standard fallback for a missing category.

other { default_value }

gender example

If you want to display the following phrase in English.

The author is other

And you also want to display the following phrases based on the gender property of the component.

The author is female

The author is male

The following code example shows how to bind the gender property of the component and use the select clause to express the previous three situations in a <span> element.

The gender property binds the outputs to each of following string values.

The select clause maps the values to the appropriate translations. The following code example shows gender property used with the select clause.

<span i18n>The author is {gender, select, male {male} female {female} other {other}}</span>

gender and minutes example

Combine different clauses together, such as the plural and select clauses. The following code example shows nested clauses based on the gender and minutes examples.

<span i18n>Updated: {minutes, plural,
  =0 {just now}
  =1 {one minute ago}
  other {{{minutes}} minutes ago by {gender, select, male {male} female {female} other {other}}}}
</span>

What's next

• Work with translation files