i18n
Интернационализация и локализация (i18n/l10n) прикладного кода — запрет языкового хардкода пользовательских строк в мультиязычных проектах. Определить, мультиязычен ли репозиторий (i18n-инфраструктура
SKILL.mdskills/i18n/SKILL.md
GitHubНавык: Интернационализация (i18n / l10n)
Правило проекта: в мультиязычном коде — ноль языкового хардкода. Любая строка, которую видит пользователь, идёт через слой перевода, а не литералом в разметке/ответе. Подход — определять и адаптировать: сначала пойми, мультиязычен ли репозиторий, потом применяй строгость по ситуации.
Навигатор. С чего начать: режим проекта → что переводится, что нет → перед сдачей анти-паттерны и чек-лист. Как писать: ключи и словари · плюрализация/род (ICU) · даты/числа/валюты (Intl). Справочно: библиотеки по стеку · frontend / backend · RTL.
Определять и адаптировать (первый шаг — всегда)
Прежде чем писать текст в код, определи режим проекта по признакам:
- i18n-пакет в
package.json:next-intl,i18next/react-i18next/i18next-http-middleware,@formatjs/*,react-intl,vue-i18n,svelte-i18n. - Каталоги словарей:
messages/,locales/,i18n/,translations/,lang/; файлы<locale>.json/.po/.ftl. - Роутинг локали: сегмент
app/[locale]/,middleware.tsс matcher локалей,next.configсi18n/localePrefix. - Конфиг локалей:
SUPPORTED_LOCALES,LOCALES,LANGUAGES,defaultLocale,<html lang>/dir.
Режимы:
- Мультиязычный (нашёл инфраструктуру и/или ≥2 локалей) → строгий запрет хардкода: каждая пользовательская строка через существующий слой перевода (
t()/useTranslation/getTranslations), в тот же формат ключей и словарей, что уже в проекте. Нет ключа — заведи его в словари всех активных локалей (недостающие — с TODO-пометкой на перевод), но не оставляй литерал в коде. - Одноязычный (инфраструктуры нет) → не навязывай полный i18n без запроса, но: строки держи вынесенными/централизованными (константы/словарь модуля), а не разбросанными по JSX; помечай найденный хардкод как потенциальный долг; форматирование дат/чисел/валют всё равно через
Intl. Так проект остаётся i18n-ready без лишнего бойлерплейта. - Неоднозначно (смешанные признаки) → уточни у пользователя целевые локали; по умолчанию считай мультиязычным, если есть хоть один пользователь-facing поток с не-дефолтным языком.
Что переводится, а что — нет
Пользовательская строка (переводится): UI-текст, заголовки, кнопки, лейблы, плейсхолдеры, подсказки/tooltips, alt, aria-label/aria-*-тексты, тосты/снекбары, сообщения об ошибках и валидации, письма/пуши/SMS, тексты PDF/квитанций, пустые состояния, единицы измерения словами.
НЕ переводится (оставляй как есть): логи и лог-сообщения (один язык, обычно English), стабильные машинные коды ошибок (AUTH_INVALID_TOKEN), идентификаторы/enum-значения, имена полей API и ключи JSON, ключи аналитики/событий, технические имена, значения в БД, регэкспы/форматные шаблоны как таковые.
Ключи и словари
- Именование ключей — по смыслу и области, не по тексту:
feature.section.action(checkout.summary.payButton), а не"Оплатить"как ключ. Единый стиль (обычноcamelCase/dot.notation) — как уже в проекте. - Где хранить: централизованные
messages/<locale>.json(next-intl) или feature-levelfeatures/<feature>/locales/<locale>.json— следуй существующей раскладке проекта, не смешивай две. - Типизация ключей: типобезопасные ключи (генерация типов из словаря /
keyof-типы next-intl /i18nextresourcesтипизация) — опечатка в ключе должна ловиться компилятором. - Никакой конкатенации переведённых кусков.
t('greeting') + nameи"Найдено " + n + " шт."— запрещено: порядок слов и согласование зависят от языка. Используй интерполяцию и ICU (ниже). - Фолбэк-локаль задан явно; отсутствующий ключ не должен рушить UI — фолбэк на дефолт + предупреждение в dev.
Плюрализация, род, интерполяция (ICU MessageFormat)
- Множественное число — через
plural(неif (n === 1)): у языков до 6 категорий (zero/one/two/few/many/other), русский/польский/арабский — нетривиальные правила.{count, plural, one {# товар} few {# товара} many {# товаров} other {# товара}}. - Род/выбор — через
select:{gender, select, female {приглашена} male {приглашён} other {приглашён(а)}}. - Интерполяция — только именованными плейсхолдерами (
{name},{count}), значения подставляет библиотека; не собирай предложение из кусков вручную. - Движки ICU: next-intl и
react-intl/@formatjs— из коробки; для i18next — плагинi18next-icu.
Форматирование (встроенный Intl — не хардкодь формат)
- Даты/время —
Intl.DateTimeFormat(locale, …)(или обёртки библиотеки); неdd.MM.yyyyстрокой. Учитывай таймзону (timeZone), храни в UTC, форматируй под пользователя. - Числа/валюты —
Intl.NumberFormat(locale, { style: 'currency', currency }); разделители, знак валюты и позиция зависят от локали. - Относительное время —
Intl.RelativeTimeFormat; списки —Intl.ListFormat; сортировка/поиск —Intl.Collator(не байтовое сравнение строк).
Библиотеки по стеку (мнение по умолчанию)
- Next.js (App Router) → next-intl: локали через
app/[locale]/,next-intl/middlewareдля роутинга/детекта, серверные переводыgetTranslationsв Server Components,useTranslationsв Client Components; локализованныеgenerateMetadataиhreflang. - React SPA (Vite/CRA) → react-i18next (
i18next+react-i18next): namespaces, ленивая загрузка,useTranslation; ICU черезi18next-icu, детект черезi18next-browser-languagedetector. - Node-бэкенд (Fastify/Express) → i18next (+
i18next-http-middleware) или@formatjs/intl: локаль изAccept-Language/профиля пользователя, перевод сообщений на границе ответа; письма/уведомления — по локали получателя. - Vue →
vue-i18n. Общий низкоуровневый слой форматирования во всех стеках — встроенныйIntl.
Frontend-специфика
- Server vs Client: на сервере (RSC) бери переводы серверным API (
getTranslations), на клиенте — хук; не тащи весь словарь в клиентский бандл — грузи только нужные namespaces/локаль. - SEO: локализованные
<title>/meta,<link rel="alternate" hreflang>,<html lang dir>под текущую локаль. - Строки — только через слой перевода; никаких литералов в JSX (кроме служебных, не видимых пользователю).
Backend-специфика
- Локализуй на границе (в ответе/письме) по
Accept-Languageили предпочтению пользователя, а не в глубине бизнес-логики. - API-контракт ошибок: отдавай стабильный машинный
code+ параметры ({ code: 'ORDER_LIMIT', params: { max: 5 } }), а готовый переведённый текст формируй на клиенте/edge — либо, если API сам отдаёт текст, выбирай язык по локали запроса. Не «зашивай» один язык в тело ответа. - Валидация (zod и т.п.): сообщения — локализуемые ключи, не хардкод-строки.
RTL и направление текста
- Поддержи RTL-локали (ar, he, fa):
dir="rtl"на<html>/контейнере, зеркалирование раскладки. - Логические CSS-свойства вместо физических:
margin-inline/padding-inline,inset-inline-start/-end,text-align: start/end(в Tailwind — логические утилитыms-*/me-*/ps-*/pe-*,start-*/end-*). Иконки направления (стрелки, chevron) — зеркаль под RTL.
Анти-паттерны (ищи и убирай)
- Литерал пользовательской строки прямо в JSX/шаблоне/HTTP-ответе в мультиязычном проекте.
- Конкатенация переведённых кусков;
"Показано " + n + " элементов"; ручная плюрализация черезif (n === 1). - Хардкод формата даты/числа/валюты (
toLocaleString()без локали тоже зависит от среды — задавай локаль явно). - Перевод того, что переводить нельзя: логов, машинных кодов ошибок, enum/идентификаторов.
- Ключ = сам текст (
t("Оплатить")); отсутствие фолбэк-локали; несогласованные наборы ключей между локалями. - Локаль не учтена в ключах кэша (один кэш на все языки) — данные/страницы кэшируются per-locale.
- Физические CSS-отступы, ломающие RTL; отсутствие
lang/dir.
Чек-лист сдачи
- Определён режим проекта (мультиязычный / одноязычный) и применена соответствующая строгость.
- Пользовательские строки вынесены в словарь/через
t(); литералов в разметке/ответах нет. - Ключи типизированы и согласованы между локалями; фолбэк-локаль задан.
- Плюрализация/род — через ICU; интерполяция — именованными плейсхолдерами.
- Даты/числа/валюты/списки — через
Intlс явной локалью и таймзоной. - Логи и машинные коды ошибок НЕ локализованы.
- RTL учтён (логические свойства,
dir), если среди локалей есть RTL.