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

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

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

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

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

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

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

Пример i18n

Следующий тег <h1> отображает простое приветствие на английском языке, "Hello 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);
  }
}

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

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

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

Именование placeholder интерполяции

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

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

Например:

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

Это эквивалент в шаблоне именования placeholder в коде компонента с $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} на имя атрибута. Используйте следующий синтаксис, чтобы назначить meaning, description и пользовательский ID.

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

Пример i18n-title

Чтобы перевести 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" />

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

В коде компонента исходный текст перевода и метаданные окружены символами backtick (`).

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

$localize`string_to_translate`;

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

$localize`:{i18n_metadata}:string_to_translate`;

Включение интерполированного текста

Включайте интерполяции в tagged message string $localize.

$localize`string_to_translate ${variable_name}`;

Именование placeholder интерполяции

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

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

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

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

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

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

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

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

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

Добавьте description текстового сообщения как значение атрибута i18n или tagged message string $localize.

Следующий пример показывает значение атрибута i18n.

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

Следующий пример показывает значение tagged message string $localize с описанием.

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

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

Пример h1

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

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

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

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

Следующий пример кода показывает значение tagged message string $localize с meaning и description.

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

Выражения ICU

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

{ component_property, icu_clause, case_statements }

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

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

Пометка множественных чисел

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

{ component_property, plural, pluralization_categories }

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

pluralization_category { }

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

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

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

Пример minutes

Если нужно отобразить следующую фразу на английском, где x — число.

updated x minutes ago

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

updated just now

updated one minute ago

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

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

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

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

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

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

{ component_property, select, selection_categories }

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

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

selection_category { text }

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

other { default_value }

Пример gender

Если нужно отобразить следующую фразу на английском.

The author is other

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

The author is female

The author is male

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

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

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

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

Пример gender и minutes

Объединяйте разные clauses вместе, например clauses plural и select. Следующий пример кода показывает вложенные clauses на основе примеров 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>

Что дальше