Manage marked text with custom IDs

The Angular extractor generates a file with a translation unit entry each of the following instances.

Each i18n attribute in a component template
Each $localize tagged message string in component code

As described in How meanings control text extraction and merges, Angular assigns each translation unit a unique ID.

The following example displays translation units with unique IDs.

messages.fr.xlf

<!-- The `messages.fr.xlf` after translation for documentation purposes --><!-- #docregion --><?xml version="1.0" encoding="UTF-8" ?><xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">  <file source-language="en" datatype="plaintext" original="ng2.template">    <body>      <!-- #docregion translated-hello-before -->      <trans-unit id="introductionHeader" datatype="html">        <source>Hello i18n!</source>        <note priority="1" from="description">An introduction header for this sample</note>        <note priority="1" from="meaning">User welcome</note>      </trans-unit>      <!-- #enddocregion translated-hello-before -->      <!-- #docregion translated-hello -->      <!-- #docregion custom-id -->      <trans-unit id="introductionHeader" datatype="html">      <!-- #enddocregion custom-id -->        <source>Hello i18n!</source>        <target>Bonjour i18n !</target>        <note priority="1" from="description">An introduction header for this sample</note>        <note priority="1" from="meaning">User welcome</note>      </trans-unit>      <!-- #enddocregion translated-hello -->      <!-- #docregion translated-other-nodes -->      <!-- #docregion generated-id -->      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">      <!-- #enddocregion generated-id -->        <source>I don&apos;t output any element</source>        <target>Je n'affiche aucun élément</target>      </trans-unit>      <trans-unit id="701174153757adf13e7c24a248c8a873ac9f5193" datatype="html">        <source>Angular logo</source>        <target>Logo d'Angular</target>      </trans-unit>      <!-- #enddocregion translated-other-nodes -->      <!-- #docregion translated-plural -->      <trans-unit id="5a134dee893586d02bffc9611056b9cadf9abfad" datatype="html">        <source>{VAR_PLURAL, plural, =0 {just now} =1 {one minute ago} other {<x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes ago} }</source>        <target>{VAR_PLURAL, plural, =0 {à l'instant} =1 {il y a une minute} other {il y a <x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes} }</target>      </trans-unit>      <!-- #enddocregion translated-plural -->      <!-- #docregion translated-select -->      <!-- #docregion translate-select-1 -->      <trans-unit id="f99f34ac9bd4606345071bd813858dec29f3b7d1" datatype="html">        <source>The author is <x id="ICU" equiv-text="{gender, select, male {...} female {...} other {...}}"/></source>        <target>L'auteur est <x id="ICU" equiv-text="{gender, select, male {...} female {...} other {...}}"/></target>      </trans-unit>      <!-- #enddocregion translate-select-1 -->      <!-- #docregion translate-select-2 -->      <trans-unit id="eff74b75ab7364b6fa888f1cbfae901aaaf02295" datatype="html">        <source>{VAR_SELECT, select, male {male} female {female} other {other} }</source>        <target>{VAR_SELECT, select, male {un homme} female {une femme} other {autre} }</target>      </trans-unit>      <!-- #enddocregion translate-select-2 -->      <!-- #enddocregion translated-select -->      <!-- #docregion translate-nested -->      <!-- #docregion translate-nested-1 -->      <trans-unit id="972cb0cf3e442f7b1c00d7dab168ac08d6bdf20c" datatype="html">        <source>Updated: <x id="ICU" equiv-text="{minutes, plural, =0 {...} =1 {...} other {...}}"/></source>        <target>Mis à jour: <x id="ICU" equiv-text="{minutes, plural, =0 {...} =1 {...} other {...}}"/></target>      </trans-unit>      <!-- #enddocregion translate-nested-1 -->      <!-- #docregion translate-nested-2 -->      <trans-unit id="7151c2e67748b726f0864fc443861d45df21d706" datatype="html">        <source>{VAR_PLURAL, plural, =0 {just now} =1 {one minute ago} other {<x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes ago by {VAR_SELECT, select, male {male} female {female} other {other} }} }</source>        <target>{VAR_PLURAL, plural, =0 {à l'instant} =1 {il y a une minute} other {il y a <x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes par {VAR_SELECT, select, male {un homme} female {une femme} other {autre} }} }</target>      </trans-unit>      <!-- #enddocregion translate-nested-2 -->      <!-- #enddocregion translate-nested -->      <!-- #docregion i18n-duplicate-custom-id -->      <trans-unit id="myId" datatype="html">        <source>Hello</source>        <target state="new">Bonjour</target>      </trans-unit>      <!-- #enddocregion i18n-duplicate-custom-id -->    </body>  </file></xliff>

When you change the translatable text, the extractor generates a new ID for that translation unit. In most cases, changes in the source text also require a change to the translation. Therefore, using a new ID keeps the text change in sync with translations.

However, some translation systems require a specific form or syntax for the ID. To address the requirement, use a custom ID to mark text. Most developers don't need to use a custom ID. If you want to use a unique syntax to convey additional metadata, use a custom ID. Additional metadata may include the library, component, or area of the application in which the text appears.

To specify a custom ID in the i18n attribute or $localize tagged message string, use the @@ prefix. The following example defines the introductionHeader custom ID in a heading element.

app.component.html

<h1 i18n="@@introductionHeader">Hello i18n!</h1>

The following example defines the introductionHeader custom ID for a variable.

variableText1 = $localize`:@@introductionHeader:Hello i18n!`;

When you specify a custom ID, the extractor generates a translation unit with the custom ID.

messages.fr.xlf

<!-- The `messages.fr.xlf` after translation for documentation purposes --><!-- #docregion --><?xml version="1.0" encoding="UTF-8" ?><xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">  <file source-language="en" datatype="plaintext" original="ng2.template">    <body>      <!-- #docregion translated-hello-before -->      <trans-unit id="introductionHeader" datatype="html">        <source>Hello i18n!</source>        <note priority="1" from="description">An introduction header for this sample</note>        <note priority="1" from="meaning">User welcome</note>      </trans-unit>      <!-- #enddocregion translated-hello-before -->      <!-- #docregion translated-hello -->      <!-- #docregion custom-id -->      <trans-unit id="introductionHeader" datatype="html">      <!-- #enddocregion custom-id -->        <source>Hello i18n!</source>        <target>Bonjour i18n !</target>        <note priority="1" from="description">An introduction header for this sample</note>        <note priority="1" from="meaning">User welcome</note>      </trans-unit>      <!-- #enddocregion translated-hello -->      <!-- #docregion translated-other-nodes -->      <!-- #docregion generated-id -->      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">      <!-- #enddocregion generated-id -->        <source>I don&apos;t output any element</source>        <target>Je n'affiche aucun élément</target>      </trans-unit>      <trans-unit id="701174153757adf13e7c24a248c8a873ac9f5193" datatype="html">        <source>Angular logo</source>        <target>Logo d'Angular</target>      </trans-unit>      <!-- #enddocregion translated-other-nodes -->      <!-- #docregion translated-plural -->      <trans-unit id="5a134dee893586d02bffc9611056b9cadf9abfad" datatype="html">        <source>{VAR_PLURAL, plural, =0 {just now} =1 {one minute ago} other {<x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes ago} }</source>        <target>{VAR_PLURAL, plural, =0 {à l'instant} =1 {il y a une minute} other {il y a <x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes} }</target>      </trans-unit>      <!-- #enddocregion translated-plural -->      <!-- #docregion translated-select -->      <!-- #docregion translate-select-1 -->      <trans-unit id="f99f34ac9bd4606345071bd813858dec29f3b7d1" datatype="html">        <source>The author is <x id="ICU" equiv-text="{gender, select, male {...} female {...} other {...}}"/></source>        <target>L'auteur est <x id="ICU" equiv-text="{gender, select, male {...} female {...} other {...}}"/></target>      </trans-unit>      <!-- #enddocregion translate-select-1 -->      <!-- #docregion translate-select-2 -->      <trans-unit id="eff74b75ab7364b6fa888f1cbfae901aaaf02295" datatype="html">        <source>{VAR_SELECT, select, male {male} female {female} other {other} }</source>        <target>{VAR_SELECT, select, male {un homme} female {une femme} other {autre} }</target>      </trans-unit>      <!-- #enddocregion translate-select-2 -->      <!-- #enddocregion translated-select -->      <!-- #docregion translate-nested -->      <!-- #docregion translate-nested-1 -->      <trans-unit id="972cb0cf3e442f7b1c00d7dab168ac08d6bdf20c" datatype="html">        <source>Updated: <x id="ICU" equiv-text="{minutes, plural, =0 {...} =1 {...} other {...}}"/></source>        <target>Mis à jour: <x id="ICU" equiv-text="{minutes, plural, =0 {...} =1 {...} other {...}}"/></target>      </trans-unit>      <!-- #enddocregion translate-nested-1 -->      <!-- #docregion translate-nested-2 -->      <trans-unit id="7151c2e67748b726f0864fc443861d45df21d706" datatype="html">        <source>{VAR_PLURAL, plural, =0 {just now} =1 {one minute ago} other {<x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes ago by {VAR_SELECT, select, male {male} female {female} other {other} }} }</source>        <target>{VAR_PLURAL, plural, =0 {à l'instant} =1 {il y a une minute} other {il y a <x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes par {VAR_SELECT, select, male {un homme} female {une femme} other {autre} }} }</target>      </trans-unit>      <!-- #enddocregion translate-nested-2 -->      <!-- #enddocregion translate-nested -->      <!-- #docregion i18n-duplicate-custom-id -->      <trans-unit id="myId" datatype="html">        <source>Hello</source>        <target state="new">Bonjour</target>      </trans-unit>      <!-- #enddocregion i18n-duplicate-custom-id -->    </body>  </file></xliff>

If you change the text, the extractor does not change the ID. As a result, you don't have to take the extra step to update the translation. The drawback of using custom IDs is that if you change the text, your translation may be out-of-sync with the newly changed source text.

Use a custom ID with a description

Use a custom ID in combination with a description and a meaning to further help the translator.

The following example includes a description, followed by the custom ID.

app.component.html

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

The following example defines the introductionHeader custom ID and description for a variable.

variableText2 = $localize`:An introduction header for this sample@@introductionHeader:Hello i18n!`;

The following example adds a meaning.

app.component.html

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

The following example defines the introductionHeader custom ID for a variable.

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

Define unique custom IDs

Be sure to define custom IDs that are unique. If you use the same ID for two different text elements, the extraction tool extracts only the first one, and Angular uses the translation in place of both original text elements.

For example, in the following code snippet the same myId custom ID is defined for two different text elements.

app.component.html

<h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>

The following displays the translation in French.

src/locale/messages.fr.xlf

<!-- The `messages.fr.xlf` after translation for documentation purposes --><!-- #docregion --><?xml version="1.0" encoding="UTF-8" ?><xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">  <file source-language="en" datatype="plaintext" original="ng2.template">    <body>      <!-- #docregion translated-hello-before -->      <trans-unit id="introductionHeader" datatype="html">        <source>Hello i18n!</source>        <note priority="1" from="description">An introduction header for this sample</note>        <note priority="1" from="meaning">User welcome</note>      </trans-unit>      <!-- #enddocregion translated-hello-before -->      <!-- #docregion translated-hello -->      <!-- #docregion custom-id -->      <trans-unit id="introductionHeader" datatype="html">      <!-- #enddocregion custom-id -->        <source>Hello i18n!</source>        <target>Bonjour i18n !</target>        <note priority="1" from="description">An introduction header for this sample</note>        <note priority="1" from="meaning">User welcome</note>      </trans-unit>      <!-- #enddocregion translated-hello -->      <!-- #docregion translated-other-nodes -->      <!-- #docregion generated-id -->      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">      <!-- #enddocregion generated-id -->        <source>I don&apos;t output any element</source>        <target>Je n'affiche aucun élément</target>      </trans-unit>      <trans-unit id="701174153757adf13e7c24a248c8a873ac9f5193" datatype="html">        <source>Angular logo</source>        <target>Logo d'Angular</target>      </trans-unit>      <!-- #enddocregion translated-other-nodes -->      <!-- #docregion translated-plural -->      <trans-unit id="5a134dee893586d02bffc9611056b9cadf9abfad" datatype="html">        <source>{VAR_PLURAL, plural, =0 {just now} =1 {one minute ago} other {<x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes ago} }</source>        <target>{VAR_PLURAL, plural, =0 {à l'instant} =1 {il y a une minute} other {il y a <x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes} }</target>      </trans-unit>      <!-- #enddocregion translated-plural -->      <!-- #docregion translated-select -->      <!-- #docregion translate-select-1 -->      <trans-unit id="f99f34ac9bd4606345071bd813858dec29f3b7d1" datatype="html">        <source>The author is <x id="ICU" equiv-text="{gender, select, male {...} female {...} other {...}}"/></source>        <target>L'auteur est <x id="ICU" equiv-text="{gender, select, male {...} female {...} other {...}}"/></target>      </trans-unit>      <!-- #enddocregion translate-select-1 -->      <!-- #docregion translate-select-2 -->      <trans-unit id="eff74b75ab7364b6fa888f1cbfae901aaaf02295" datatype="html">        <source>{VAR_SELECT, select, male {male} female {female} other {other} }</source>        <target>{VAR_SELECT, select, male {un homme} female {une femme} other {autre} }</target>      </trans-unit>      <!-- #enddocregion translate-select-2 -->      <!-- #enddocregion translated-select -->      <!-- #docregion translate-nested -->      <!-- #docregion translate-nested-1 -->      <trans-unit id="972cb0cf3e442f7b1c00d7dab168ac08d6bdf20c" datatype="html">        <source>Updated: <x id="ICU" equiv-text="{minutes, plural, =0 {...} =1 {...} other {...}}"/></source>        <target>Mis à jour: <x id="ICU" equiv-text="{minutes, plural, =0 {...} =1 {...} other {...}}"/></target>      </trans-unit>      <!-- #enddocregion translate-nested-1 -->      <!-- #docregion translate-nested-2 -->      <trans-unit id="7151c2e67748b726f0864fc443861d45df21d706" datatype="html">        <source>{VAR_PLURAL, plural, =0 {just now} =1 {one minute ago} other {<x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes ago by {VAR_SELECT, select, male {male} female {female} other {other} }} }</source>        <target>{VAR_PLURAL, plural, =0 {à l'instant} =1 {il y a une minute} other {il y a <x id="INTERPOLATION" equiv-text="{{minutes}}"/> minutes par {VAR_SELECT, select, male {un homme} female {une femme} other {autre} }} }</target>      </trans-unit>      <!-- #enddocregion translate-nested-2 -->      <!-- #enddocregion translate-nested -->      <!-- #docregion i18n-duplicate-custom-id -->      <trans-unit id="myId" datatype="html">        <source>Hello</source>        <target state="new">Bonjour</target>      </trans-unit>      <!-- #enddocregion i18n-duplicate-custom-id -->    </body>  </file></xliff>

Both elements now use the same translation (Bonjour), because both were defined with the same custom ID.

<h3>Bonjour</h3><!-- ... --><p>Bonjour</p>