I18n

---
name: i18n
description: "Интернационализация: словари, ICU plural/gender, Intl formatting, RTL и поиск пользовательских строк мимо i18n-слоя."
---

# Навык: Интернационализация (i18n / l10n)

Правило: **в мультиязычном коде — ноль языкового хардкода**. Любая строка, которую видит пользователь, идёт через слой перевода. Подход — **определять и адаптировать**.

**Навигатор.** С чего начать: [режим проекта](#определять-и-адаптировать-сначала--всегда) → [что переводится, что нет](#что-переводится-а-что-нет) → перед сдачей [анти-паттерны](#анти-паттерны) и [чек-лист](#чек-лист). Как писать: [ключи и словари](#ключи-словари-интерполяция) · [плюрализация/род и Intl](#плюрализациярод-и-форматирование). Справочно: [библиотеки по стеку](#библиотеки-по-стеку) · [Frontend / Backend / RTL](#frontend--backend--rtl).

## Определять и адаптировать (сначала — всегда)
Признаки мультиязычности репо: i18n-пакет в `package.json` (`next-intl`, `i18next`/`react-i18next`, `@formatjs/*`, `vue-i18n`); каталоги `messages/`/`locales/`/`i18n/` с `<locale>.json`; сегмент `app/[locale]/`, middleware локалей; `SUPPORTED_LOCALES`/`LANGUAGES`/`defaultLocale`.
- **Мультиязычный** → строгий запрет хардкода: каждая пользовательская строка через `t()`/`useTranslations`/`getTranslations` в существующий формат ключей; нет ключа — заведи в словари всех локалей, но не оставляй литерал.
- **Одноязычный** → полный i18n не навязывай, но строки держи вынесенными (не в JSX), хардкод помечай как долг; даты/числа/валюты всё равно через `Intl`.
- **Неоднозначно** → уточни целевые локали; по умолчанию считай мультиязычным при наличии не-дефолтного языкового потока.

## Что переводится, а что нет
Переводится: UI-текст, кнопки, лейблы, плейсхолдеры, `alt`/`aria-*`, тосты, сообщения об ошибках/валидации, письма/пуши, PDF/квитанции, пустые состояния.
НЕ переводится: логи (один язык), стабильные машинные коды ошибок, идентификаторы/enum, имена полей API/ключи JSON, ключи аналитики.

## Ключи, словари, интерполяция
- Ключи по смыслу (`feature.section.action`), не по тексту; единый стиль; типизация ключей (опечатка ловится компилятором).
- Хранение — как в проекте: централизованный `messages/<locale>.json` или feature-level `locales/`.
- Никакой конкатенации переведённых кусков; интерполяция — именованными плейсхолдерами (`{name}`, `{count}`).
- Фолбэк-локаль задан; отсутствующий ключ не рушит UI.

## Плюрализация/род и форматирование
- Множественное число — ICU `plural` (не `if (n===1)`; у ru/pl/ar сложные правила); род/выбор — ICU `select`.
- Даты/время — `Intl.DateTimeFormat` (+ таймзона, хранение в UTC); числа/валюты — `Intl.NumberFormat` (`currency`); относительное время — `RelativeTimeFormat`; списки — `ListFormat`; сортировка — `Intl.Collator`. Формат не хардкодить.

## Библиотеки по стеку
- **Next.js App Router** → **next-intl**: `app/[locale]/`, `next-intl/middleware`, `getTranslations` (сервер) / `useTranslations` (клиент), локализованные `generateMetadata`/`hreflang` (см. `$nextjs`).
- **React SPA** → **react-i18next** (`i18next`): namespaces, ленивая загрузка, `useTranslation`, ICU через `i18next-icu` (см. `$react`).
- **Node-бэкенд** → **i18next** (+ `i18next-http-middleware`) или `@formatjs/intl`: локаль из `Accept-Language`/профиля, перевод на границе ответа; письма — по локали получателя (см. `$backend-architecture`, `$api-design`).

## Frontend / Backend / RTL
- **Frontend:** server (`getTranslations`) vs client (хук); не тащи весь словарь в бандл; SEO — `hreflang`, `<html lang dir>`.
- **Backend:** локализуй на границе; API отдаёт стабильный `code` + параметры, а не готовый переведённый текст (или переводит по локали запроса); валидация — локализуемые ключи (см. `$error-handling`).
- **RTL** (ar/he/fa): `dir="rtl"`, логические CSS-свойства (`margin-inline`, Tailwind `ms-*`/`me-*`/`ps-*`/`pe-*`, `start/end`), зеркалирование иконок (см. `$tailwind`).

## Анти-паттерны
Литерал строки в JSX/ответе (мультиязычный проект); конкатенация переводов и `"Показано " + n`; ручная плюрализация; хардкод формата даты/валюты; перевод логов/кодов ошибок; ключ = текст; отсутствие фолбэка; локаль не учтена в кэш-ключах; физические CSS-отступы, ломающие RTL.

## Чек-лист
Режим определён; строки через `t()`; ключи типизированы и согласованы; ICU для plural/род; `Intl` для дат/чисел/валют; логи и коды ошибок не переведены; RTL учтён при наличии RTL-локалей.