Базовые методы получения переводов

Основным механизмом извлечения переводов в i18next выступает функция t. Она является точкой доступа к словарю переводов и обеспечивает разрешение ключей в соответствующие строки с учётом текущего языка, namespace, контекста и параметров форматирования.

В базовом виде вызов выглядит следующим образом:

t('welcome.message')

Ключ может быть как простым, так и составным, отражающим структуру JSON-словаря:

{
  "welcome": {
    "message": "Добро пожаловать"
  }
}

Тогда обращение t('welcome.message') вернёт строку "Добро пожаловать".

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

i18next поддерживает точечную нотацию для работы с вложенными объектами. По умолчанию разделителем является символ .:

t('user.profile.name')

При необходимости разделитель может быть изменён через конфигурацию keySeparator, что особенно важно при наличии ключей, содержащих точки как часть имени.

Использование i18n.t вне контекста React и хуков

Помимо функции t, доступной через хуки или контекст, существует прямой доступ через экземпляр i18n:

import i18n from 'i18next'

i18n.t('welcome.message')

Этот способ используется в слоях приложения, где отсутствует доступ к React-хукам или DI-контексту, например в утилитах, сервисах и middleware.

Функция i18n.t идентична по поведению, но зависит от глобального состояния экземпляра i18next.

Работа с namespace

i18next поддерживает разделение переводов на пространства имён. Это позволяет структурировать словари по модулям приложения.

Пример использования namespace:

t('header:title')

Где header — namespace, а title — ключ.

Если namespace не указан явно, используется namespace по умолчанию, заданный в конфигурации:

defaultNS: 'common'

При работе с несколькими namespace функция t может принимать третий аргумент или использовать расширенный синтаксис:

t('title', { ns: 'header' })

Параметры функции t()

Функция t поддерживает объект опций, который позволяет управлять поведением подстановки и форматирования.

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

Одной из ключевых возможностей является подстановка динамических значений:

t('greeting', { name: 'Алексей' })

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

{
  "greeting": "Привет, {{name}}"
}

результат будет:

Привет, Алексей

Интерполяция поддерживает числовые значения, строки и частично вложенные структуры в зависимости от конфигурации интерполятора.

Значение по умолчанию

Если ключ отсутствует в словаре переводов, может быть задано значение по умолчанию:

t('unknown.key', { defaultValue: 'Значение по умолчанию' })

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

Работа с множественным числом

i18next поддерживает плюрализацию через суффиксы ключей:

{
  "item_one": "1 элемент",
  "item_other": "{{count}} элементов"
}

Вызов:

t('item', { count: 5 })

Механизм автоматически выбирает соответствующую форму на основе правила языка.

Контекстные переводы

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

{
  "friend_male": "друг",
  "friend_female": "подруга"
}
t('friend', { context: 'female' })

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

Возврат объектов переводов

i18next может возвращать не только строки, но и структуры данных:

t('menu', { returnObjects: true })

Если перевод задан как объект:

{
  "menu": {
    "home": "Главная",
    "about": "О нас"
  }
}

результатом будет JavaScript-объект:

{
  home: "Главная",
  about: "О нас"
}

Проверка существования ключа

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

i18n.exists('welcome.message')

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

Фиксированная функция t через getFixedT

Для закрепления языка и namespace используется getFixedT, создающий преднастроенную версию функции:

const t = i18n.getFixedT('ru', 'common')

t('welcome.message')

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

Приоритет разрешения ключей

При вызове t система проходит несколько уровней поиска:

  1. Проверка namespace (если указан)
  2. Поиск ключа в текущем языке
  3. Переход к fallback-языку
  4. Использование defaultValue при отсутствии результата

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

Разделители ключей и неймспейсов

i18next использует два ключевых разделителя:

  • keySeparator — разделение вложенных ключей
  • nsSeparator — разделение namespace и ключа

По умолчанию:

keySeparator: '.'
nsSeparator: ':'

Пример комбинированного использования:

t('auth:login.title')

где auth — namespace, login.title — путь к значению.

Поведение при отключённых ключах

При настройке:

returnNull: false
returnEmptyString: false

определяется поведение функции t при отсутствии перевода. Вместо null или пустой строки возвращается fallback-значение или ключ, что влияет на стабильность UI-слоя.

Форматирование результата

Результат функции t всегда приводится к строке, за исключением случаев:

  • returnObjects: true
  • кастомных форматов через интерполятор
  • функций постобработки (postProcess)

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

Постобработка значений

i18next поддерживает цепочку постобработчиков:

t('price', { postProcess: 'currency' })

Постобработка применяется после интерполяции и позволяет форматировать данные (например, валюты, даты, числа) без изменения исходного словаря.

Работа с fallback-языками

Если перевод отсутствует в текущем языке, система переходит к fallback-языкам, определённым в конфигурации:

fallbackLng: 'en'

Это влияет непосредственно на результат t, так как функция возвращает первое найденное совпадение по цепочке языков.

Использование контекста и параметров одновременно

Комбинация параметров позволяет формировать сложные правила выбора строки:

t('cart.item', {
  count: 3,
  context: 'warning',
  defaultValue: 'Элементы корзины'
})

В таких случаях происходит одновременная обработка:

  • плюрализации
  • контекста
  • интерполяции
  • fallback-значений

что формирует итоговую строку на основе совокупности правил разрешения.

Оглавление