Как работать с формами множественного числа, датами и числами

Пусть локаль определяет грамматику и форматирование, а приложение управляет значениями, единицами измерения и часовыми поясами.

Чтобы показать количество элементов, нужно решить две задачи: определить, какое число передаёт приложение и как выразить это количество на языке читателя. С датами и денежными суммами действует тот же принцип. Сохраняйте значения в структурированном виде до вывода, чтобы осознанно выбирать грамматические формы, разделители, валюту и часовой пояс.

В этих примерах используется @lingo.dev/react. У нативных систем ресурсов свой синтаксис сообщений и свои генераторы. Сходство с нотацией ICU не делает все среды выполнения взаимозаменяемыми.

Передавайте средству форматирования сообщение целиком #

В компоненте внутри LingoProvider используйте числовое значение количества в сообщении с формами множественного числа:

tsx
const l = useLingo();

const label = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the shopping cart" },
);

Импортируйте useLingo из @lingo.dev/react. count — числовое значение, которое передаёт приложение. Среда выполнения создаёт сообщение ICU и форматирует перевод из каталога с учётом текущей локали. one и other — грамматические категории. Если просто добавить переведённое существительное после отформатированного числа, вы потеряете возможность выбирать нужную форму и менять порядок слов.

Вспомогательная функция plural создаёт именованные категории CLDR, но не включает ветви для точных числовых значений, такие как =0. Чтобы задать особое сообщение для нулевого значения с учётом логики продукта, используйте текстовый способ вывода с явным выражением ICU:

ts
l.text("{count, plural, =0 {No items} one {# item} other {# items}}", {
  context: "Cart count with a distinct empty state",
  values: { count },
});

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

Для выбора варианта по смыслу используйте стабильные значения селектора:

ts
l.select(role, {
  admin: "Manage team settings",
  member: "View team settings",
  other: "View settings",
}, { context: "Settings action for the user's team role" });

Приложение передаёт role. Переводите сообщения в ветвях, сохраняя admin, member и обязательную резервную ветвь other. Для неизвестного значения используется other.

Различайте порядковый номер и количество #

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

ts
l.text("You finished {position, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}", {
  context: "Participant's finishing position in a competition",
  values: { position },
});

Эти окончания — особенность английского исходного текста, а не универсальное правило. Перевод должен выражать позицию по правилам своего языка. Передача values включает форматирование при текстовом выводе. Сгенерированные объявления проверяют соответствие вызова контракту, но не проверяют каждую вложенную ветвь ICU.

Явно указывайте валюту и единицы для процентов #

Используйте числовые суммы с соответствующим кодом валюты:

ts
const price = l.currency(1234.5, "EUR");
const discount = l.percent(0.15);

Первый вызов форматирует сумму в евро, но не переводит её из другой валюты в евро. Второй выражает пятнадцать процентов, потому что принимает долю единицы. Если передать 15, получится другая величина. Когда вставляете эти отформатированные строки в предложение, передавайте их через именованные values, а не создавайте новую исходную строку.

Вспомогательные функции форматирования также работают с числами, единицами измерения, списками и другими значениями, которые форматируются с помощью Intl. Проверьте значения по умолчанию и поддерживаемые параметры каждой функции. Форматирование с учётом локали не переводит все нестандартные обозначения единиц, а недопустимые параметры всё равно могут привести к ошибке.

Определите, что означает дата и в каком часовом поясе её показывать #

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

Для момента времени укажите часовой пояс, в котором его нужно показать:

ts
const instant = new Date("2026-01-02T00:30:00Z");

const date = l.date(instant, { timeZone: "UTC" });
const time = l.time(instant, { timeZone: "UTC" });

Эти вспомогательные функции форматируют значения с учётом текущей локали и показывают время в UTC. Стандартные API, на которых они основаны, можно использовать и напрямую:

ts
new Intl.NumberFormat("de-DE", {
  style: "currency", currency: "EUR",
}).format(1234.5);

new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium", timeZone: "UTC",
}).format(new Date("2026-01-02T00:30:00Z"));

Используйте в сообщениях с разметкой только поддерживаемую грамматику #

l.rich сопоставляет именованные теги с компонентами React и подставляет значения в простые плейсхолдеры. Средство сложного форматирования ICU из l.text здесь не используется. Предложение вроде «Прочитайте наши <link>условия доставки</link> для {region}» подходит для этого способа вывода, если код передаёт функцию отображения ссылки и значение региона. Добавление внутрь такого сообщения форм множественного числа или порядковых числительных не включит поддержку ICU.

Задавайте взаимодействия в коде. Если нужно совместить разметку и грамматику, выбирайте поддерживаемую структуру сообщения. Неизвестные теги остаются обычным текстом, а возможности попарного сопоставления вложенных одноимённых тегов ограничены. См. Интерактивные сообщения с разметкой.

Проверяйте случаи, в которых меняется смысл #

Проверьте значения количества 0, 1, 2, число побольше и дробное число, если продукт его допускает. Для английских порядковых числительных включите 1, 2, 3, 11, 12, 13 и 21. Для языков перевода используйте формулировки, ожидаемые в соответствующей локали. Проверьте неизвестное значение селектора, отрицательные суммы там, где они имеют смысл, и один и тот же момент времени в двух часовых поясах около полуночи.

Для этих проверок загружайте реальные каталоги переводов на целевые языки. Если перевод отсутствует или пуст, вместо него может использоваться исходный текст. Поэтому правдоподобный результат сам по себе ещё не подтверждает, что нужный текст переведён. Сверьте отображаемые значения с нужным количеством, датой и смыслом сообщения, а затем проверьте язык перевода.