Перейти к основному содержимому

Технические требования i18n

В данном разделе описаны правила организации ключей, управления namespaces, работы с динамическим контентом и типизации.

Организация ключей​

MUST​

  1. Ключи стабильные и не зависят от конкретного текста на языке.
  2. Формат ключей: lowercase + разделитель . (точка).
  3. Схема именования: {feature}.{scope}.{element}.
  4. Не использовать: пробелы, camelCase, UPPER_CASE, кириллицу или длинные предложения в качестве ключей.

SHOULD​

Ключи отражают структуру UI/домена:

  • common.* — общие слова/кнопки (только строки, переиспользуемые в 3+ местах).
  • errors.* — ошибки.
  • validation.* — сообщения валидации.
  • feature.<name> или pages.<route> — специфичный контент фичи или страницы.

FORBIDDEN​

  1. Индексированные ключи: Text_1, label_2, t100.
  2. Неспецифичные имена: message, value, text.

Стратегии Namespace'ов​

MUST​

  1. Переводы делятся на namespaces по доменам или фичам. Избегайте монолитного файла (например, один en.json на 5000+ ключей).
  2. Разделение необходимо для:
    • Оптимизации размера bundle.
    • Сохранения модульности.
    • Избежания конфликтов при параллельной разработке.

Пример структуры​

i18n/
  locales/
    en/
      common.json      # кнопки/короткие действия
      errors.json      # универсальные ошибки
      validation.json  # сообщения валидатора
      pages/           # тексты страниц
        home.json
        settings.json

Плюралы и интерполяция​

MUST​

  1. Плюралы реализуются только через механизм i18n-библиотеки (ICU MessageFormat), а не через ручные if/else.
  2. Интерполяция: используйте именованные параметры {{ name }}.
  3. Запрещена конкатенация строк через +, так как это ломает грамматику при переводе.

Rich Text​

MUST: Не разбивать предложение на части в коде, если внутри есть ссылка или выделение жирным. Используйте компоненты интерполяции (например, <Trans> в react-i18next или аналоги в next-intl).

Форматирование (Dates, Numbers, Currency)​

MUST​

  1. Все даты, числа и валюты форматируются через Intl API (или обертки библиотеки i18n).
  2. Формат должен зависеть от текущей locale.
  3. Запрещено хардкодить форматы (например, ${day}.${month}.${year}).

Загрузка переводов с помощь SSG/SSR (Next.js / Astro)​

Переводы должны быть доступны до рендера страницы (SSR/SSG), чтобы избежать:

  • "мигания" текста
  • лишних запросов с клиента

TypeScript и типизация​

Для проектов на Next.js (с использованием next-intl) обязательно использование Type Augmentation для получения автокомплита ключей и проверки их существования на этапе компиляции.

// global.d.ts
import messages from '@/i18n/locales/en/common.json';

declare module 'next-intl' {
  interface AppConfig {
    Messages: typeof messages;
  }
}