@intlayer/docs 9.4.1 → 9.4.3

package/blog/ru/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Форматирование дат и чисел по локалям с помощью Intl"
+description: Вам, скорее всего, не нужна сторонняя библиотека форматирования. Как Intl работает с датами, числами, валютами и списками, цена кэширования и баг с часовым поясом в продакшене.
+keywords:
+  - форматирование дат по локали
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - форматирование валюты locale
+  - относительное время
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Форматирование дат и чисел по локалям с помощью Intl
+
+Перевод строк — это лишь видимая верхушка айсберга интернационализации. Вторая половина, порождающая регулярные баг-репорты, это форматирование: когда пользователь из Германии видит `1,234.56` вместо `1.234,56`, пользователь из Японии видит `08/02/2026` и читает это как август, или когда дата по-разному отображается на сервере и клиенте, ломая гидратацию React.
+
+Ни для чего из этого не нужны сторонние библиотеки. Стандартный `Intl` встроен в любую современную среду исполнения.
+
+## Содержание
+
+<TOC/>
+
+## Начните с удаления самописных хелперов для дат
+
+Практически в любой кодовой базе найдется функция `formatDate`, написанная задолго до того, как кто-то задумался о локализации. В ней захардкожен жесткий порядок, разделитель и, как правило, английские названия месяцев.
+
+```ts
+// То, что нужно удалить:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` заменяет ее полностью и работает корректно для любой локали:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+То же самое касается чисел. Метод `toFixed(2)` повсеместно выдает `1234.56`, что является ошибкой для большей части Европы.
+
+## Что охватывает `Intl`
+
+| API                       | Для чего использовать                                      |
+| :------------------------ | :--------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Даты и время с пресетами `dateStyle` / `timeStyle`         |
+| `Intl.NumberFormat`       | Дроби, валюты, проценты, единицы измерения, компактный вид |
+| `Intl.RelativeTimeFormat` | "3 дня назад", "через 2 часа"                              |
+| `Intl.ListFormat`         | "a, b и c" против "a, b, and c"                            |
+| `Intl.PluralRules`        | Определение грамматической категории плюрализации чисел    |
+| `Intl.Collator`           | Корректная сортировка строк с учетом правил языка          |
+
+`Intl.Collator` часто несправедливо забывают. Обычный `array.sort()` на строках сортирует по кодовым точкам Unicode, из-за чего буквы с диакритикой улетают в конец за букву `z`, а шведская `ö` оказывается не на своем месте. Если вы сортируете видимые пользователю списки, делайте это через коллатор.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("ru").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Предпочитайте пресеты ручной сборке параметров
+
+`dateStyle` и `timeStyle` позволяют самой локали определить правильный порядок полей и разделители. Перечисление `year`, `month` и `day` по отдельности дает избыточный контроль, который чаще вредит, так как принятый порядок элементов различается в зависимости от страны, и вы рискуете перезаписать правила CLDR своими ошибочными догадками.
+
+```ts
+// Локаль сама определяет структуру:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Вы навязали структуру вручную и ошиблись для других стран:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Указывайте отдельные поля явным образом только тогда, когда строгая фиксированная ширина продиктована дизайном, например в узкой колонке таблицы.
+
+## Создание форматтеров ресурсоемко
+
+Это ключевой нюанс производительности. Инициализация объекта `Intl.NumberFormat` загружает увесистые локализационные данные, и эта операция значительно дороже последующего вызова `.format()`. Вызов конструктора внутри цикла рендеринга на тысячу строк приводит к ощутимым задержкам.
+
+```ts
+// Пересоздает форматтер на каждой строке таблицы:
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Создается один раз и переиспользуется:
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+Методы `toLocaleDateString()` и `toLocaleString()` страдают той же скрытой проблемой: каждый их вызов под капотом конструирует новый форматтер. Это незаметно для единичного значения, но недопустимо для списков.
+
+Кэшируйте форматтеры по комбинации локали и параметров:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## Баг с часовым поясом, возникающий только в продакшене
+
+Этот сценарий отнял у разработчиков множество рабочих часов. Сервер рендерит дату при SSR, браузер выполняет гидратацию на клиенте, и React выбрасывает ошибку hydration mismatch, так как на сервере и в браузере получились разные текстовые строки.
+
+Причина в том, что `Intl.DateTimeFormat` использует текущий часовой пояс операционной системы, если он не указан явно. Сервер продакшена работает по UTC, а ноутбук разработчика — в домашнем часовом поясе. В результате баг невозможно воспроизвести локально, и он стреляет только в продакшене.
+
+```ts
+// Сервер в UTC и браузер в UTC+9 сгенерируют разный текст. Ошибка гидратации.
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Полная согласованность:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Три рабочих подхода:
+
+- **Зафиксировать часовой пояс** на сервере и передавать его явно. Надежно и детерминированно, но все видят время по UTC.
+- **Рендерить только на клиенте**, оставляя нейтральный плейсхолдер во время серверного прохода. Точно для каждого пользователя, но дает небольшой визуальный сдвиг.
+- **Сохранять часовой пояс пользователя** и прокидывать его на сервер и клиент. Идеальный результат, требующий чуть больше подготовительной работы.
+
+Какой бы путь вы ни выбрали, всегда передавайте `timeZone` явно для любых дат, участвующих в SSR и гидратации. Дата без указания часового пояса — это дата с двумя несовпадающими значениями.
+
+## Валюте нужна валюта, а не локаль
+
+Локаль и валюта независимы друг от друга. `fr-FR` не означает евро по умолчанию: французский пользователь вполне может просматривать инвойс в долларах США.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+Локаль управляет разделителями, группировкой разрядов и положением символа. Валюта берется из ваших прикладных данных. Попытка вывести одно из другого неизбежно приведет к ошибкам в бухгалтерии.
+
+Обратите внимание на параметр `currencyDisplay`. В интерфейсах, где сосуществуют разные валюты со знаком доллара, значение `"code"` исключает путаницу между долларами США, Канады и Австралии.
+
+## Относительное время воспринимается лучше абсолютного
+
+Для недавних событий текст "2 часа назад" воспринимается гораздо легче точной временной метки, и `Intl.RelativeTimeFormat` берет это на себя.
+
+```ts
+new Intl.RelativeTimeFormat("ru", { numeric: "auto" }).format(-1, "day");
+// "вчера"
+```
+
+Параметр `numeric: "auto"` как раз и возвращает "вчера" вместо сухого "1 день назад". Без него вы получите механический числовой формат.
+
+## Что добавляет Intlayer
+
+Intlayer оборачивает эти возможности в легковесные хелперы с автоматическим кэшированием, избавляя вас от ручного поддержания Map, и автоматически подставляет активную локаль из контекста.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1 234,5"
+currency(1234.5, { currency: "EUR" }); // "1 234,50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 часа назад"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 километров"
+compact(1200); // "1,2 тыс."
+list(["яблоко", "банан", "апельсин"]); // "яблоко, банан и апельсин"
+```
+
+Функция `date()` также поддерживает пресеты (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`). Для React и Vue доступны готовые хуки и composables, получающие активный язык непосредственно из контекста приложения.
+
+Это слой кэширования и подстановки локали по умолчанию над стандартным API платформы. Сама логика форматирования полностью опирается на нативный `Intl`. Все сигнатуры описаны в [документации форматтеров](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/formatters.md).
+
+## Частые ошибки
+
+- **`toLocaleDateString()` без указания локали.** Берет локаль операционной системы, которая на сервере зависит от настроек контейнера.
+- **Форматирование в цикле без кэширования.** Создание форматтера забирает львиную долю процессорного времени.
+- **Отсутствие `timeZone` на изоморфных датах.** Гарантирует ошибки гидратации, которые не воспроизводятся локально.
+- **Определение валюты по локали.** `fr-FR` не гарантирует расчеты в евро.
+- **Обычный `sort()` для видимых списков.** Всегда применяйте `Intl.Collator`.
+- **Ручной хардкод названий месяцев или дней.** Они уже содержатся в базе CLDR для всех языков.
+- **Отказ от `numeric: "auto"` для относительного времени.** Приводит к фразам вроде "1 день назад" там, где есть слово вчера.
+
+## Полезные материалы
+
+- [Форматтеры и утилиты локалей: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/formatters.md)
+- [Справочник конфигурации](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)
+- [Бенчмарки производительности фреймворков](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/benchmark/index.md)
+- [Адаптер совместимости react-intl](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/compat/react-intl.md)
+- [Формат сообщений ICU: множественные формы, селекторы и числовые скелетоны](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ru/icu_message_format.md)
+- [Как тестировать переводы, включая форматтеры и плюрализацию](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ru/i18n_testing_strategies.md)
+- [Что на самом деле охватывает интернационализация](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ru/what_is_internationalization.md)

package/blog/ru/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Как находить недостающие переводы раньше ваших пользователей"
+description: Ошибки отсутствия переводов происходят молча. Почему фолбэк маскирует их, какие четыре уровня обнаружения действительно работают и как ронять сборку на непереведенных ключах.
+keywords:
+  - поиск отсутствующих переводов
+  - пропущенные ключи перевода
+  - i18n аудит
+  - непереведенные строки
+  - покрытие переводов
+  - i18n lint
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Как находить недостающие переводы раньше ваших пользователей
+
+Отсутствие перевода практически никогда не выбрасывает ошибку. В зависимости от конфигурации приложение либо покажет английский текст японскому пользователю, либо выведет `checkout.summary.total` прямо на странице в продакшене. Оба варианта попадают в релиз, проходят код-ревью и обнаруживаются клиентами, а не вами.
+
+## Содержание
+
+<TOC/>
+
+## Это работает независимо от используемой библиотеки
+
+Здесь нет привязки к какому-то одному стеку. Описанные ниже уровни обнаружения одинаково функционируют в i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate или Lingui, поскольку все они одинаково разрешают ключи и одинаково дают сбои.
+
+Инструменты также переносимы. Если ваши переводы сейчас хранятся в JSON-каталогах, [плагин Sync JSON](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/plugins/sync-json.md) подключает Intlayer к этим файлам, предоставляя команды аудита, автозаполнения и тестирования без переноса контента и без изменения импортов:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // или "icu" для next-intl / react-intl
+    }),
+  ],
+};
+
+export default config;
+```
+
+Если вы хотите сохранить привычный runtime API, [адаптеры совместимости](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/compat/index.md) создают псевдонимы для `useTranslation`, `$t` и других функций на уровне сборщика. В любом случае воспринимайте приведенные команды как наглядную реализацию концепции, а не жесткое требование.
+
+## Почему они незаметны
+
+Любая библиотека i18n разрешает ключ по одной цепочке: найти в активной локали, откатиться к локали по умолчанию и, если ничего не найдено, вернуть сам строковый ключ. Именно этот последний шаг создает проблему. Нет исключений, нет предупреждений в продакшене и нет упавших тестов, потому что ничто в пайплайне не считает отсутствие перевода аномалией.
+
+Фолбэк делает ситуацию еще хуже. Страница, которая молча отрендерилась на английском, выглядит совершенно нормальной для англоязычного разработчика и проходит все автоматические проверки. Ошибка видна только тому, кто не понимает этот язык.
+
+Поэтому вопрос звучит не «как обрабатывать отсутствующие переводы во время выполнения». А «как сделать так, чтобы PR с отсутствующим переводом было невозможно смержить».
+
+## Четыре уровня, на которых их можно поймать
+
+Каждый уровень отслеживает то, что упускают остальные. Имеет смысл использовать сразу несколько.
+
+| Уровень       | Обнаруживает                                | Пропускает                                     |
+| :------------ | :------------------------------------------ | :--------------------------------------------- |
+| Типы          | Ключи, которых вообще не существует         | Ключ существует, но не переведен в `ja`        |
+| Линтер        | Захардкоженные строки, не переданные в i18n | Ключи, отсутствующие в каталоге                |
+| Аудит         | Покрытие локалями всех объявленных ключей   | Текст, который вообще не был помечен переводом |
+| Тесты рендера | Ключи, которые разрешаются с ошибками       | Всё, что не покрыто тестами                    |
+
+Чаще всего команды упускают третью строчку: они уверены в валидности ключей, но ничто не проверяет, что во всех восемнадцати локалях действительно есть значения.
+
+## Уровень 1: делайте ключ типом, а не строкой
+
+`t("checkout.summry.total")` — это опечатка, которая успешно компилируется. Если ваши ключи — обычные строки, каждое переименование несет риск в продакшене, а каждое удаление оставляет ключ-сироту.
+
+Типизированные ключи превращают это в ошибку сборки. `react-i18next` поддерживает это через declaration merging, `next-intl` выводит типы из структуры сообщений, Lingui генерирует идентификаторы из исходного текста, а Intlayer создает строгие типы из файлов объявлений контента. Все варианты работают; различается лишь объем ручной настройки.
+
+Этот уровень необходим, но недостаточен. Типы описывают структуру вашего каталога по умолчанию. Они ничего не говорят о том, есть ли у этого ключа перевод на корейский.
+
+## Уровень 2: линтинг строк, которые так и не стали ключами
+
+Перевод, который вы не можете найти, часто оказывается тем, который никогда не был вынесен в словарь. Захардкоженный текст в компоненте невидим для любого аудита каталогов, поскольку для инструментов этой строки не существует.
+
+Плагин ESLint для Intlayer решает эту проблему правилом `no-raw-text`, дополненным `no-unused-content` для обратной ситуации: контент объявлен, но больше нигде не используется.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content` предотвращает бесконтрольное разрастание каталогов. Мертвые ключи не ломают сборку, но неоправданно увеличивают счета за услуги переводчиков. Полный список правил смотрите в [документации плагина ESLint](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/eslint.md).
+
+## Уровень 3: аудит покрытия локалей
+
+Именно этот уровень дает прямой ответ на главный вопрос. Intlayer поставляет его в виде CLI-команды:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Она считывает настроенные локали и объявленные словари, после чего выдает отчет: каким ключам не хватает каких языков и в каком файле.
+
+Важная деталь перед добавлением в скрипты: **CLI выводит отчет, но завершается с кодом 0.** Если вы вставите команду в пайплайн в надежде сломать билд, вы получите зеленую галочку с простыней текста в логах, которую никто не станет читать. Для остановки билда используйте программный API, описанный ниже.
+
+## Уровень 4: проверки через assertions в тестовом наборе
+
+`listMissingTranslations()` возвращает те же данные аудита в виде объекта, что идеально подходит для создания блокирующего барьера (gate).
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("не содержит пропусков в обязательных локалях", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Возвращаются три полезных поля:
+
+- `missingTranslations`: по каждому ключу указано, каких локалей не хватает и в каком файле. Это выводится при падении теста.
+- `missingLocales`: объединение всех недостающих локалей по всем ключам.
+- `missingRequiredLocales`: ограничено списком `requiredLocales` из конфигурации (или всеми локалями, если параметр не задан).
+
+## `requiredLocales` делает проверку реалистичной
+
+Поддержка восемнадцати языков вовсе не означает, что все восемнадцать должны быть переведены на 100% для выката релиза. У большинства команд есть критический уровень языков, блокирующий поставку, и уровень языков, которые допереводятся по мере готовности.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Без `requiredLocales` каждая объявленная локаль считается строго обязательной, и билд будет красным, пока не подоспеет последний перевод. Именно из-за этого проверки часто просто отключают целиком.
+
+## Поиск пробелов, уже попавших в продакшен
+
+Предыдущие шаги защищают от появления новых проблем. Для приложения, которое уже выкачено, эффективны два приема:
+
+**Псевдолокализация.** Запустите тестовую локаль, где каждый символ трансформируется, например `[!!! Ĉĥéçķöũţ !!!]`. Всё, что останется на чистом английском, захардкожено в коде. Это находит за 10 минут то, что аудит каталогов не способен увидеть по своей архитектуре.
+
+**Краулинг собственного сайта.** Если у вас локализованные URL, скачайте выборку страниц для каждого языка и выполните поиск английских строк в HTML. Страница по адресу `/ja/`, содержащая "Add to cart", указывает либо на пропущенный перевод, либо на непредвиденный фолбэк.
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Заполнение пробелов
+
+Когда вы знаете, чего не хватает, `intlayer fill` заполняет пустые значения, а опция `autoFill` может создавать файлы деклараций для каждой локали по мере их добавления. См. [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/autoFill.md).
+
+Здесь важно смотреть на вещи трезво: автоматический машинный перевод превращает _видимую_ брешь в _невидимую_. Ключ заполнен, тесты зеленые, но текст никто не вычитывал. Используйте это для снятия блокировки релиза, но обязательно отдавайте на проверку человеку тексты, влияющие на финансовые и юридические решения.
+
+## Распространенные ошибки
+
+- **Считать фолбэк инструментом защиты.** Это механизм аварийного отображения, а не страховка. Тихо показанная английская страница — это незамеченный баг.
+- **Полагаться на вывод CLI для блокировки CI.** `intlayer content test` завершается с кодом 0. Используйте тесты с ассертами.
+- **Делать обязательными абсолютно все локали.** Проверку отключат при первой же сорванной поставке.
+- **Аудит каталогов без проверки реального рендеринга.** Захардкоженные строки по определению не видны в каталогах.
+- **Тестирование только языка по умолчанию.** Это единственный язык, который гарантированно не будет отсутствовать.
+- **Завершение процесса лишь машинным заполнением.** Зеленые тесты при невычитанных текстах.
+
+## Полезные материалы
+
+- [Тестирование контента: аудит CLI, программный API и UI-ассерты](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/testing.md)
+- [Правила плагина ESLint, включая `no-raw-text` и `no-unused-content`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/eslint.md)
+- [autoFill: создание файлов деклараций для каждой локали](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/autoFill.md)
+- [Справочник конфигурации: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/configuration.md)
+- [Отчеты производительности фреймворков](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/benchmark/index.md)
+- [Адаптер совместимости i18next](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ru/compat/i18next.md)
+- [Что на самом деле охватывает интернационализация](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ru/what_is_internationalization.md)
+- [i18n на уровне компонентов против централизованной схемы](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ru/per-component_vs_centralized_i18n.md)