Настройка behavior

Поведение i18next в рантайме определяется набором конфигурационных параметров, передаваемых в init. Эти параметры формируют стратегию загрузки ресурсов, обработки ключей, интерполяции, fallback-механизмы и реакции на отсутствующие переводы. Изменение этих настроек напрямую влияет на предсказуемость локализации и структуру переводческих файлов.

import i18n from 'i18next';

i18n.init({
  lng: 'en',
  fallbackLng: 'en',
  debug: true
});

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

Режим отложенной инициализации

Параметр initImmediate управляет тем, выполняется ли инициализация синхронно или через асинхронный цикл событий.

i18n.init({
  initImmediate: false
});

Синхронная инициализация применяется в средах, где требуется гарантированная готовность переводов до первого рендера интерфейса. Асинхронный режим позволяет подключать backend-загрузчики и удалённые источники ресурсов.

Управление языком и fallback-цепочками

Механизм выбора языка задаётся через lng, а резервные языки через fallbackLng. Поведение fallback может быть как линейным, так и иерархическим.

i18n.init({
  lng: 'ru',
  fallbackLng: ['en', 'de']
});

При отсутствии ключа в основном языке выполняется последовательный обход цепочки fallback. Если цепочка не задана, используется встроенный язык по умолчанию.

Дополнительно может использоваться nonExplicitSupportedLngs, который расширяет поиск на региональные варианты языка, например en-US → en.

Структура ключей и разделители

Обработка ключей переводов зависит от параметров keySeparator и nsSeparator.

i18n.init({
  keySeparator: '.',
  nsSeparator: ':'
});

При отключении разделителей ключи интерпретируются как плоские строки:

i18n.init({
  keySeparator: false
});

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

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

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

i18n.init({
  interpolation: {
    escapeValue: false,
    prefix: '{{',
    suffix: '}}'
  }
});

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

Настройки prefix и suffix позволяют изменить синтаксис плейсхолдеров:

// перевод
"welcome": "Hello {{name}}"

Дополнительно поддерживаются функции форматирования значений через format:

i18n.init({
  interpolation: {
    format: (value, format) => {
      if (format === 'uppercase') return value.toUpperCase();
      return value;
    }
  }
});

Обработка отсутствующих переводов

Поведение при отсутствии ключей контролируется через saveMissing, missingKeyHandler и связанные параметры.

i18n.init({
  saveMissing: true
});

При включении saveMissing библиотека инициирует вызов backend-плагина для сохранения отсутствующих ключей в хранилище.

Обработчик missingKeyHandler позволяет перехватывать такие случаи:

i18n.init({
  missingKeyHandler: (lng, ns, key) => {
    console.log(lng, ns, key);
  }
});

Управление пространствами имён

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

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

Поведение загрузки ресурсов зависит от defaultNS. Если ключ не содержит явного namespace, используется значение по умолчанию.

Контроль загрузки ресурсов

Параметр load задаёт стратегию загрузки языковых вариантов:

  • currentOnly — только текущий язык
  • languageOnly — без региональных расширений
  • all — загрузка всех доступных вариантов
i18n.init({
  load: 'languageOnly'
});

В связке с backend-плагинами это влияет на количество сетевых запросов и структуру кэша.

Поведение при форматировании массивов и объектов

Параметры returnObjects и returnEmptyString управляют типами возвращаемых значений.

i18n.init({
  returnObjects: true
});

При включении returnObjects допускается возврат вложенных структур:

{
  "menu": {
    "file": "File",
    "edit": "Edit"
  }
}

Без этого параметра результат будет приведён к строковому виду или проигнорирован.

Обработка массивов в переводах

Поведение массива значений регулируется через joinArrays.

i18n.init({
  joinArrays: '\n'
});

При наличии массива переводов:

{
  "list": ["one", "two", "three"]
}

результат будет объединён указанным разделителем. При false массив возвращается без преобразования.

Постобработка переводов

Параметр postProcess позволяет подключать цепочку трансформаций результата.

i18n.init({
  postProcess: ['sprintf']
});

Постпроцессоры применяются после интерполяции и перед возвратом строки. Это позволяет реализовать сложные сценарии форматирования, включая pluralization hooks, markdown parsing или кастомные трансформации.

Управление логированием и отладкой

Поведение диагностического вывода контролируется через debug.

i18n.init({
  debug: true
});

В режиме отладки выводятся:

  • загруженные ресурсы
  • отсутствующие ключи
  • fallback-цепочки
  • конфликты namespace

Дополнительно может использоваться logLevel, задающий фильтрацию сообщений:

i18n.init({
  logLevel: 'warn'
});

Поведение при загрузке языков на лету

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

i18n.init({
  cleanCode: true
});

При включённой нормализации pt-BR может быть преобразован в pt для унифицированной загрузки.

Обработка переменных в ключах

Параметр skipOnVariables определяет, выполняется ли fallback при наличии переменных в ключе.

i18n.init({
  skipOnVariables: true
});

Если ключ содержит динамическую часть, система может пропускать fallback-обход, чтобы избежать лишних вычислений.

Кэширование и частичная загрузка

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

i18n.init({
  partialBundledLanguages: true
});

Это снижает объём загружаемых ресурсов, но требует строгого соответствия структуры namespace.

Контроль возврата значений

Параметр returnNull и returnEmptyString определяют, как интерпретируются отсутствующие или пустые переводы.

i18n.init({
  returnNull: false,
  returnEmptyString: false
});

При отключении returnNull отсутствующий ключ будет возвращать сам ключ или fallback-значение, а не null.

Согласованность поведения при runtime-обновлениях

При использовании методов changeLanguage и динамической загрузки ресурсов поведение сохраняется через внутренний store конфигурации. Изменение параметров после init не всегда приводит к немедленному эффекту, если не выполнен принудительный пересбор контекста:

i18n.reloadResources();

Поведение системы при этом зависит от backend-адаптера и стратегии кэширования, используемой в приложении.

Оглавление