Полный обзор опций инициализации

i18next — ядро системы интернационализации, вокруг которого строится конфигурация загрузки ресурсов, обработка ключей, работа с множественными языками и интеграция с фреймворками. i18next предоставляет единый механизм инициализации через i18next.init(options), где поведение библиотеки определяется большим набором параметров.

Инициализация выполняется через конфигурационный объект:

i18next.init({
  lng: 'ru',
  fallbackLng: 'en',
  resources: {}
})

Конфигурация влияет на:

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

Управление языком

lng

Определяет текущий язык:

lng: 'ru'

Особенности:

  • приоритетнее детекторов языка
  • может быть переопределён через changeLanguage
  • поддерживает массив в некоторых сценариях

fallbackLng

Определяет язык-запасной вариант:

fallbackLng: 'en'

Расширенные формы:

fallbackLng: {
  'ru': ['uk', 'en'],
  'default': ['en']
}

Поведение:

  • используется при отсутствии ключей
  • может быть цепочкой языков
  • поддерживает региональные fallback (например en-US → en)

supportedLngs

Ограничивает список допустимых языков:

supportedLngs: ['en', 'ru', 'de']

Особенности:

  • предотвращает загрузку лишних ресурсов
  • отключает автоматический fallback вне списка при nonExplicitSupportedLngs: false

nonExplicitSupportedLngs

nonExplicitSupportedLngs: true
  • разрешает использование региональных языков (en-US)
  • упрощает поддержку локалей

Пространства имён (namespaces)

ns

ns: ['common', 'home']

Определяет набор пространств имён для переводов.

defaultNS

defaultNS: 'common'

Используется при отсутствии явного namespace в ключе.

fallbackNS

fallbackNS: 'common'

Применяется при отсутствии ключа в основном namespace.

Ресурсы переводов

resources

Inline-ресурсы:

resources: {
  en: {
    common: {
      hello: 'Hello'
    }
  },
  ru: {
    common: {
      hello: 'Привет'
    }
  }
}

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

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

partialBundledLanguages

partialBundledLanguages: true

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

Загрузка переводов

backend

Конфигурация backend-адаптера:

backend: {
  loadPath: '/locales/{{lng}}/{{ns}}.json'
}

Используется с плагинами загрузки.

preload

preload: ['en', 'ru']

Загружает языки заранее при инициализации.

initImmediate

initImmediate: false
  • true — асинхронная инициализация
  • false — синхронная инициализация (устаревший подход в новых архитектурах)

Обработка ключей

keySeparator

keySeparator: '.'

Позволяет использовать вложенные ключи:

t('menu.home.title')

Отключение:

keySeparator: false

nsSeparator

nsSeparator: ':'

Пример:

t('common:hello')

ignoreJSONStructure

ignoreJSONStructure: false

Контролирует обработку вложенных JSON-структур.

Интерполяция

interpolation

interpolation: {
  escapeValue: false,
  prefix: '{{',
  suffix: '}}'
}

Основные параметры:

  • escapeValue — отключение экранирования (важно для React)
  • prefix / suffix — синтаксис переменных
  • format — кастомные форматтеры

Пример:

t('hello_user', { name: 'Alex' })

Шаблон:

Hello {{name}}

interpolation.format

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

Обработка отсутствующих ключей

saveMissing

saveMissing: true

Отправляет отсутствующие ключи в backend.

missingKeyHandler

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

Позволяет логировать или обрабатывать отсутствующие переводы.

parseMissingKeyHandler

parseMissingKeyHandler: (key) => `??${key}??`

Формирует fallback-значение.

Поведение значений

returnNull

returnNull: false
  • true — возвращает null при отсутствии ключа
  • false — продолжает fallback-цепочку

returnEmptyString

returnEmptyString: false

Контролирует поведение пустых переводов.

returnObjects

returnObjects: true

Позволяет возвращать объекты:

t('user')

Результат:

{ name: "Alex", age: 20 }

Режим отладки

debug

debug: true
  • выводит информацию о загрузке ресурсов
  • показывает ошибки ключей
  • полезен в разработке

Кэширование и производительность

cleanCode

cleanCode: true

Убирает лишние ключи и оптимизирует структуру.

load

load: 'languageOnly'

Варианты:

  • languageOnly → en
  • currentOnly → en-US
  • all → полная загрузка

Поддержка фреймворков

react integration

react: {
  useSuspense: true
}

Влияет на:

  • поведение Suspense
  • загрузку переводов
  • ререндер компонентов

Плагины детекции языка

detection

detection: {
  order: ['querystring', 'cookie'],
  caches: ['cookie']
}

Источники:

  • URL параметр
  • cookies
  • localStorage
  • headers
  • navigator

Преобразование JSON версий

compatibilityJSON

compatibilityJSON: 'v4'

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

События и хуки

init

init: (options, callback) => {}

Позволяет:

  • перехватывать завершение инициализации
  • выполнять пост-обработку

postProcess

postProcess: ['upperCase']

Применяет трансформации после перевода.

Дополнительные параметры

joinArrays

joinArrays: false

Управляет объединением массивов переводов.

overloadTranslationOptionHandler

overloadTranslationOptionHandler: args => args[1]

Позволяет изменять поведение параметров t().

pluralSeparator

pluralSeparator: '_'

Пример ключей:

apple
apple_plural

contextSeparator

contextSeparator: '_'

Используется для контекстных переводов:

button_save_male
button_save_female
Оглавление