Как форматировать значения с учётом локали

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

Переведённые сообщения тоже содержат значения: цены, даты, количества и списки. Объект Lingo форматирует их с учётом своей активной локали, не обращаясь к каталогу. Используйте тот же объект, который выводит текст сообщения, чтобы и текст, и значения соответствовали одной локали.

Числа и количества #

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en-US");
const price = l.currency(29.99, "USD");
const completion = l.percent(0.125, { maximumFractionDigits: 1 });
const temperature = l.unit(32, "celsius", { unitDisplay: "long" });

Метод для цен форматирует переданную сумму в долларах США, но не конвертирует валюту. Для процентов передавайте долю: 0.125 отображается как 12.5%, а 12.5 означало бы 1250%. Так же работает и метод для единиц измерения: он добавляет обозначение к переданному значению в градусах Цельсия, не пересчитывая его.

МетодПараметры после значения
num(value: number)Intl.NumberFormatOptions — необязательно.
currency(value: number, currency: string)Код валюты, затем необязательные параметры форматирования числа.
percent(value: number)Необязательные параметры форматирования числа.
unit(value: number, unit: string)Идентификатор единицы измерения, затем необязательные параметры форматирования числа.
compact(value: number)Необязательные параметры форматирования числа.
fileSize(bytes: number)Без параметров.

Все методы возвращают строки. Методы для валют, процентов и единиц измерения всегда используют соответствующий стиль. compact после применения остальных параметров принудительно задаёт компактную запись.

fileSize делит значение на степени 1024 и использует фиксированные обозначения B, KB, MB, GB, TB и PB. Число форматируется с учётом локали: без дробной части для байтов и максимум с одним знаком после разделителя для более крупных единиц. 1024 отображается как 1 KB, а ноль — как 0 B. Передавайте неотрицательное целое число байтов. Для отрицательных значений и дробного числа байтов не предусмотрено подходящих правил отображения, а обозначения вроде GB не переводятся на французский как Go.

Даты, время и относительные смещения #

ts
const instant = new Date("2026-10-10T12:00:00Z");
const timestamp = l.datetime(instant, { timeZone: "UTC" });
const date = l.date(instant, {
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
  timeZone: "UTC",
});
const age = l.relative(-3, "day", { numeric: "auto" });

Эти вызовы используют l из предыдущего примера. date, time и datetime принимают Date | number, затем необязательный параметр Intl.DateTimeFormatOptions. Числовые временные метки задаются в миллисекундах, а не в секундах Unix. По умолчанию используются соответственно средний формат даты, краткий формат времени и их сочетание.

Если задать отдельные поля, например year или hour, стили по умолчанию не применяются. Явно заданные стили могут заменить стили по умолчанию, но несовместимые сочетания стилей и отдельных полей могут привести к исключению во встроенном Intl. Задайте часовой пояс, если сервер и браузер должны показывать одну и ту же дату.

relative(value, unit, options?) принимает число со знаком, Intl.RelativeTimeFormatUnit и необязательный параметр Intl.RelativeTimeFormatOptions. Метод форматирует переданное смещение. Вычисляйте разницу с опорным моментом времени в коде приложения и обновляйте её при необходимости: метод не считывает текущее время и не планирует обновления.

Списки и работа с текстом #

МетодРезультат и поведение
list(items: string[], options?: Intl.ListFormatOptions)Строка, объединяющая уже выбранные подписи. По умолчанию — с соединительным союзом.
displayName(code, type)Локализованное название или undefined. Тип — language, region, script или currency. Встроенный резервный механизм может вернуть сам код.
sort(items: string[], options?: Intl.CollatorOptions)Новый массив, отсортированный по правилам локали. Исходный массив не меняется.
segment(text, granularity?)Сегменты строки: по умолчанию используется grapheme, также доступны word/sentence. В режиме разбиения на слова результат включает и сегменты из пробельных символов.

displayName перехватывает ошибки встроенного API и возвращает undefined. Остальные методы не перехватывают ошибки таким образом. Проверяйте коды локалей и параметры на входе в приложение.

Учитывайте поддерживаемую среду выполнения #

Эти вспомогательные методы используют встроенные NumberFormat, DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames, Collator и Segmenter. Пакет не заменяет отсутствующие встроенные API и не предоставляет данные локалей для всех сред выполнения.

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