i18n

Интернационализация и локализация (i18n/l10n) прикладного кода — запрет языкового хардкода пользовательских строк в мультиязычных проектах. Определить, мультиязычен ли репозиторий (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-level features/<feature>/locales/<locale>.json — следуй существующей раскладке проекта, не смешивай две.
  • Типизация ключей: типобезопасные ключи (генерация типов из словаря / keyof-типы next-intl / i18next resources типизация) — опечатка в ключе должна ловиться компилятором.
  • Никакой конкатенации переведённых кусков. 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.