Как форматировать значения с учётом локали
Форматируйте числа, даты, списки и текст с помощью встроенного Intl, передавая нужные для отображения единицы измерения и данные о времени.
Переведённые сообщения тоже содержат значения: цены, даты, количества и списки. Объект Lingo форматирует их с учётом своей активной локали, не обращаясь к каталогу. Используйте тот же объект, который выводит текст сообщения, чтобы и текст, и значения соответствовали одной локали.
Числа и количества #
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.
Даты, время и относительные смещения #
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. При гидратации должны совпадать не только локаль, но и временная метка, часовой пояс и опорный момент для относительного времени.