Управление помеченным текстом с помощью пользовательских ID

Экстрактор Angular генерирует файл с записью единицы перевода для каждого из следующих случаев:

Каждый атрибут i18n в шаблоне компонента
Каждая строка сообщения, помеченная тегом $localize в коде компонента

Как описано в разделе Как смысловые значения управляют извлечением текста и слияниями, Angular присваивает каждой единице перевода уникальный ID.

В следующем примере показаны единицы перевода с уникальными 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>

При изменении переводимого текста экстрактор генерирует новый ID для этой единицы перевода. В большинстве случаев изменения в исходном тексте также требуют изменения перевода. Поэтому использование нового ID позволяет синхронизировать изменения текста с переводами.

Однако некоторые системы перевода требуют определенной формы или синтаксиса для ID. Чтобы выполнить это требование, используйте пользовательский ID для маркировки текста. Большинству разработчиков не нужно использовать пользовательский ID. Если вы хотите использовать уникальный синтаксис для передачи дополнительных метаданных, используйте пользовательский ID. Дополнительные метаданные могут включать библиотеку, компонент или область приложения, в которой появляется текст.

Чтобы указать пользовательский ID в атрибуте i18n или строке сообщения с тегом $localize, используйте префикс @@. В следующем примере определяется пользовательский ID introductionHeader в элементе заголовка.

app.component.html

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

В следующем примере определяется пользовательский ID introductionHeader для переменной.

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

Когда вы указываете пользовательский ID, экстрактор генерирует единицу перевода с этим 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>

Если вы измените текст, экстрактор не изменит ID. В результате вам не нужно предпринимать дополнительных шагов для обновления перевода. Недостатком использования пользовательских ID является то, что при изменении текста ваш перевод может рассинхронизироваться с новым исходным текстом.

Использование пользовательского ID с описанием

Используйте пользовательский ID в сочетании с описанием и смысловым значением (meaning), чтобы дополнительно помочь переводчику.

Следующий пример включает описание, за которым следует пользовательский ID.

app.component.html

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

В следующем примере определяются пользовательский ID introductionHeader и описание для переменной.

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

В следующем примере добавляется смысловое значение.

app.component.html

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

В следующем примере определяется пользовательский ID introductionHeader для переменной.

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

Определение уникальных пользовательских ID

Убедитесь, что определяемые вами пользовательские ID уникальны. Если вы используете один и тот же ID для двух разных текстовых элементов, инструмент извлечения извлечет только первый из них, и Angular будет использовать перевод вместо обоих исходных текстовых элементов.

Например, в следующем фрагменте кода один и тот же пользовательский ID myId определен для двух разных текстовых элементов.

app.component.html

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

Ниже показан перевод на французский язык.

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>

Оба элемента теперь используют один и тот же перевод (Bonjour), так как оба были определены с одним и тем же пользовательским ID.

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