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

      <!-- The `messages.fr.xlf` after translation for documentation purposes --><?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>      <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>      <trans-unit id="introductionHeader" datatype="html">        <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>      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">        <source>I don'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>      <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>      <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>      <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>      <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>      <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>      <trans-unit id="myId" datatype="html">        <source>Hello</source>        <target state="new">Bonjour</target>      </trans-unit>    </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/app.component.html

      <h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>

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

      <!-- The `messages.fr.xlf` after translation for documentation purposes --><?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>      <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>      <trans-unit id="introductionHeader" datatype="html">        <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>      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">        <source>I don'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>      <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>      <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>      <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>      <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>      <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>      <trans-unit id="myId" datatype="html">        <source>Hello</source>        <target state="new">Bonjour</target>      </trans-unit>    </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/app.component.html

      <h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>

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/app.component.html

      <h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>

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/app.component.html

      <h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><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 --><?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>      <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>      <trans-unit id="introductionHeader" datatype="html">        <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>      <trans-unit id="ba0cc104d3d69bf669f97b8d96a4c5d8d9559aa3" datatype="html">        <source>I don'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>      <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>      <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>      <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>      <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>      <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>      <trans-unit id="myId" datatype="html">        <source>Hello</source>        <target state="new">Bonjour</target>      </trans-unit>    </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>