Директивы для i18n

Система ключей как базовая директива перевода

В основе работы i18next лежит принцип ключевой адресации строк. Любой текст в интерфейсе представляется как уникальный ключ, который сопоставляется с набором переводов в ресурсных файлах.

Структура ресурсов:

{
  "header": {
    "title": "Главная",
    "subtitle": "Панель управления"
  }
}

Вызов:

i18next.t('header.title');

Ключевая директива здесь — t() как функция разрешения ключа. Она выполняет не просто поиск строки, а полноценное построение локализованного значения с учётом контекста, параметров и языка.

Интерполяция как директива подстановки значений

Интерполяция позволяет внедрять динамические данные в переводимые строки без конкатенации.

Шаблон:

{
  "welcome_user": "Добро пожаловать, {{name}}"
}

Использование:

i18next.t('welcome_user', { name: 'Алексей' });

Механизм интерполяции выполняется на уровне движка перевода и поддерживает:

  • строковые значения
  • числовые параметры
  • вложенные объекты
  • функции форматирования

Дополнительно доступна защита от XSS через экранирование значений.

Директива множественного числа (pluralization)

Система множественных форм является одной из ключевых директив локализации.

Структура:

{
  "item": "{{count}} элемент",
  "item_plural": "{{count}} элементов"
}

Вызов:

i18next.t('item', { count: 5 });

Механизм автоматически выбирает нужную форму на основе правил языка. Для языков со сложной морфологией используется расширенная система категорий (zero, one, few, many).

Контекстная директива (context)

Контекст позволяет уточнять перевод в зависимости от дополнительного параметра.

Пример ресурса:

{
  "button": "Кнопка",
  "button_male": "Мужская кнопка",
  "button_female": "Женская кнопка"
}

Использование:

i18next.t('button', { context: 'male' });

Контекст формирует модифицированный ключ, не изменяя исходную структуру данных. Это позволяет масштабировать словари без дублирования логики.

Нестинг как директива композиции строк

Нестинг используется для включения одной локализованной строки в другую.

Пример:

{
  "error": "Ошибка: $t(common.network)"
}

Общий словарь:

{
  "common": {
    "network": "Проблема сети"
  }
}

Результат:

i18next.t('error');

Механизм nesting обеспечивает:

  • повторное использование переводов
  • централизованное управление терминологией
  • снижение дублирования ключей

Директива форматирования значений

Форматирование применяется для чисел, дат и валют через постпроцессоры или внешние модули.

Пример числового форматирования:

i18next.t('price', {
  val: 2500,
  formatParams: {
    val: {
      currency: 'KZT'
    }
  }
});

Ресурс:

{
  "price": "Цена: {{val, currency}}"
}

Форматирование реализуется через расширяемые функции, подключаемые к pipeline обработки перевода.

Директива fallback-языков

Fallback-механизм определяет поведение при отсутствии ключа в текущей локали.

Конфигурация:

i18next.init({
  fallbackLng: 'en'
});

Алгоритм:

  1. Поиск ключа в текущем языке
  2. Поиск в fallback-языке
  3. Возврат ключа или дефолтного значения

Эта директива обеспечивает устойчивость интерфейса при неполных переводах.

Namespace-директива разделения словарей

Namespaces позволяют логически разделять переводы по модулям приложения.

Структура:

i18next.init({
  ns: ['common', 'dashboard', 'auth'],
  defaultNS: 'common'
});

Использование:

i18next.t('login.title', { ns: 'auth' });

Преимущества:

  • изоляция модулей
  • ускорение загрузки переводов
  • упрощение поддержки больших проектов

Директива детектирования языка

Система определения языка может работать через плагины детектирования:

  • URL параметр
  • localStorage
  • cookie
  • HTTP заголовки

Конфигурация:

i18next.init({
  detection: {
    order: ['cookie', 'localStorage', 'navigator']
  }
});

Директива определяет приоритет источников языка и влияет на выбор активной локали.

PostProcessor-директива обработки результата

PostProcessor позволяет модифицировать итоговую строку после выполнения всех операций перевода.

Пример регистрации:

i18next.use({
  type: 'postProcessor',
  process(value) {
    return value.toUpperCase();
  }
});

Использование:

i18next.t('welcome', { postProcess: 'uppercase' });

Механизм используется для:

  • стилизации текста
  • фильтрации содержимого
  • логирования переводов

Директива сохранения ресурсов (backend loading)

Загрузка переводов осуществляется через backend-плагины.

Пример:

import Backend from 'i18next-http-backend';

i18next.use(Backend).init({
  backend: {
    loadPath: '/locales/{{lng}}/{{ns}}.json'
  }
});

Эта директива определяет стратегию получения переводов:

  • статические файлы
  • API-сервер
  • CDN

Директива обновления ресурсов в runtime

i18next поддерживает динамическое добавление переводов:

i18next.addResourceBundle('ru', 'common', {
  new_key: 'Новое значение'
});

Также возможно полное обновление:

i18next.reloadResources();

Эта директива используется в системах с горячей локализацией без перезагрузки приложения.

Директива приоритетов разрешения ключей

При наличии конфликтующих ключей используется цепочка разрешения:

  1. namespace
  2. язык
  3. fallback язык
  4. дефолтное значение

Эта система формирует предсказуемую модель выбора строки при неоднозначных запросах.

Директива escaping и безопасность значений

По умолчанию интерполяция экранирует HTML-символы:

i18next.t('text', { value: '<script>' });

Настройка:

i18next.init({
  interpolation: {
    escapeValue: true
  }
});

При необходимости работы с HTML экранирование может быть отключено, но это переносит ответственность за безопасность на уровень приложения.

Директива ключевых пространств и вложенных структур

Поддержка глубоких структур позволяет формировать иерархии переводов:

{
  "profile": {
    "settings": {
      "title": "Настройки профиля"
    }
  }
}

Доступ:

i18next.t('profile.settings.title');

Такая модель снижает когнитивную нагрузку при масштабировании словарей и обеспечивает естественную группировку интерфейсных элементов.

Оглавление