Подготовка компонента к переводу

Чтобы подготовить проект к переводу, выполните следующие действия.

• Используйте атрибут i18n, чтобы пометить текст в шаблонах компонентов
• Используйте атрибут i18n-, чтобы пометить текстовые значения атрибутов в шаблонах компонентов
• Используйте помеченную строку сообщения $localize, чтобы пометить текстовые строки в коде компонента

Пометка текста в шаблоне компонента

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

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

Используйте атрибут i18n, чтобы пометить статическое текстовое сообщение в шаблонах компонентов для перевода. Добавьте его к каждому тегу элемента, содержащему неизменяемый текст, который нужно перевести.

Пример i18n

Следующий тег <h1> отображает простое приветствие на английском языке: «Привет, i18n!».

<h1>Hello i18n!</h1>

Чтобы пометить приветствие для перевода, добавьте атрибут i18n к тегу <h1>.

<h1 i18n>Hello i18n!</h1>

Использование условного оператора с i18n

Следующий тег <div> будет отображать переведенный текст в составе div и aria-label в зависимости от состояния переключателя

<button type="button" (click)="toggleDisplay()">Toggle</button>
<div i18n [attr.aria-label]="toggleAriaLabel()">{{ toggle() }}</div>

import {Component, computed, signal} from '@angular/core';
import {$localize} from '@angular/localize/init';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  minutes = 0;
  gender = 'female';
  fly = true;
  logo = '${this.baseUrl}/angular.svg';
  readonly toggle = signal(false);
  readonly toggleAriaLabel = computed(() => {
    return this.toggle()
      ? $localize`:Toggle Button|A button to toggle status:Show`
      : $localize`:Toggle Button|A button to toggle status:Hide`;
  });

  inc(i: number) {
    this.minutes = Math.min(5, Math.max(0, this.minutes + i));
  }
  male() {
    this.gender = 'male';
  }
  female() {
    this.gender = 'female';
  }
  other() {
    this.gender = 'other';
  }
  toggleDisplay() {
    this.toggle.update((toggle) => !toggle);
  }
}

Перевод встроенного текста без элемента HTML

Используйте элемент <ng-container>, чтобы задать поведение перевода для определенного текста, не меняя способ его отображения.

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

Присвоение имени заполнителю интерполяции

По умолчанию Angular создает имя заполнителя для каждой интерполяции в переводимом сообщении. Чтобы присвоить ему осмысленное имя, которое поможет переводчикам понять контекст, добавьте комментарий //i18n(ph="name") внутрь интерполяции.

<element i18n>{{ expression //i18n(ph="placeholder_name") }}</element>

Например:

<p i18n>Hello, {{ username //i18n(ph="name") }}!</p>

Это эквивалентно присвоению имени заполнителю в коде компонента с помощью $localize:

$localize`Hello, ${username}:name:!`;

Пометка атрибутов элементов для перевода

В шаблоне компонента метаданные i18n задаются значением атрибута i18n-{attribute_name}.

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

Атрибуты элементов HTML содержат текст, который следует переводить вместе с остальным отображаемым текстом в шаблоне компонента.

Используйте i18n-{attribute_name} с любым атрибутом любого элемента и замените {attribute_name} именем атрибута. Используйте следующий синтаксис, чтобы задать значение, описание и пользовательский идентификатор.

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

Пример i18n-title

Чтобы перевести заголовок изображения, рассмотрите этот пример. В следующем примере показано изображение с атрибутом title.

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

Чтобы пометить атрибут title для перевода, выполните следующее действие.

Добавьте атрибут i18n-title

В следующем примере показано, как пометить атрибут title тега img, добавив i18n-title.

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

Пометка текста в коде компонента

В коде компонента исходный текст для перевода и метаданные заключаются в обратные кавычки (`).

Используйте помеченную строку сообщения $localize, чтобы пометить строку в коде для перевода.

$localize`string_to_translate`;

Метаданные i18n заключаются в двоеточия (:) и располагаются перед исходным текстом для перевода.

$localize`:{i18n_metadata}:string_to_translate`;

Добавление интерполированного текста

Добавляйте интерполяции в помеченную строку сообщения $localize.

$localize`string_to_translate ${variable_name}`;

Присвоение имени заполнителю интерполяции

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

Условный синтаксис для переводов

return this.show ? $localize`Show Tabs` : $localize`Hide tabs`;

Метаданные i18n для перевода

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

Следующие параметры предоставляют контекст и дополнительную информацию, чтобы уменьшить вероятность недопонимания при переводе.

Дополнительные сведения о пользовательских идентификаторах см. в разделе Управление помеченным текстом с пользовательскими идентификаторами.

Добавление полезных описаний и значений

Чтобы точно перевести текстовое сообщение, предоставьте переводчику дополнительную информацию или контекст.

Добавьте описание текстового сообщения в качестве значения атрибута i18n или помеченной строки сообщения $localize.

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

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

В следующем примере показано значение помеченной строки сообщения $localize с описанием.

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

Переводчику также может понадобиться знать значение или назначение текстового сообщения в контексте конкретного приложения, чтобы перевести его так же, как и другой текст с тем же значением. Начните значение атрибута i18n с значения и отделите его от описания символом |: {meaning}|{description}.

Пример h1

Например, можно указать, что тег <h1> является заголовком сайта и должен переводиться одинаково независимо от того, используется ли он как заголовок или упоминается в другом разделе текста.

В следующем примере показано, как указать, что тег <h1> должен переводиться как заголовок или при упоминании в другом месте.

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

В результате любой текст, помеченный site header, будет переведен совершенно одинаково, поскольку его значение совпадает.

В следующем примере кода показано значение помеченной строки сообщения $localize со значением и описанием.

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

ICU-выражения

ICU-выражения позволяют помечать альтернативный текст в шаблонах компонентов в зависимости от условий. ICU-выражение включает свойство компонента, условие ICU и варианты, заключенные в фигурные скобки ({ и }).

{ component_property, icu_clause, case_statements }

Свойство компонента определяет переменную. Условие ICU определяет тип условного текста.

Чтобы упростить перевод, используйте условия International Components for Unicode (ICU) с регулярными выражениями.

Пометка форм множественного числа

В разных языках действуют разные правила образования множественного числа, что усложняет перевод. Поскольку в других локалях количественные значения выражаются иначе, может потребоваться задать категории множественного числа, не совпадающие с английскими. Используйте условие plural, чтобы пометить выражения, которые могут потерять смысл при дословном переводе.

{ component_property, plural, pluralization_categories }

После категории множественного числа укажите текст по умолчанию (на английском языке), заключив его в фигурные скобки ({ и }).

pluralization_category { }

Для английского языка доступны следующие категории множественного числа; в других локалях они могут отличаться.

Если ни одна категория множественного числа не подходит, Angular использует other в качестве стандартного варианта для отсутствующей категории.

other { default_quantity }

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;
}

Пример с минутами

Допустим, вы хотите отобразить следующую фразу на английском языке, где x — число.

updated x minutes ago

Также нужно отображать следующие фразы в зависимости от количества x.

updated just now

updated one minute ago

Используйте разметку HTML и интерполяции. В следующем примере кода показано, как использовать условие plural, чтобы выразить три предыдущих ситуации в элементе <span>.

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

Рассмотрим следующие сведения о предыдущем примере кода.

{{minutes}} — это интерполяция.

Пометка альтернатив и вложенных выражений

Условие select помечает варианты альтернативного текста на основе заданных строковых значений.

{ component_property, select, selection_categories }

Переведите все альтернативы, чтобы отображать альтернативный текст в зависимости от значения переменной.

После категории выбора укажите текст (на английском языке), заключив его в фигурные скобки ({ и }).

selection_category { text }

В разных локалях используются разные грамматические конструкции, что усложняет перевод. Используйте разметку HTML. Если ни одна категория выбора не подходит, Angular использует other в качестве стандартного варианта для отсутствующей категории.

other { default_value }

Пример с полом

Допустим, вы хотите отобразить следующую фразу на английском языке.

The author is other

Также нужно отображать следующие фразы в зависимости от свойства компонента gender.

The author is female

The author is male

В следующем примере кода показано, как привязать свойство компонента gender и использовать условие select, чтобы выразить три предыдущих ситуации в элементе <span>.

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

Условие select сопоставляет значения с соответствующими переводами. В следующем примере кода показано свойство gender, используемое с условием select.

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

Пример с полом и минутами

Объединяйте разные условия, например plural и select. В следующем примере кода показаны вложенные условия на основе примеров с gender и minutes.

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

Что дальше