Работа с методом t()

i18next предоставляет центральный механизм локализации через функцию t(), которая выполняет извлечение перевода по ключу и обработку дополнительных параметров: интерполяции, множественного числа, контекстов, пространств имён и fallback-логики. В архитектуре библиотеки именно t() выступает точкой доступа к языковым ресурсам и инкапсулирует всю логику разрешения ключей перевода.

Функция t() вызывается через экземпляр i18next и имеет следующую концептуальную сигнатуру:

t(key, options?, defaultValue?)
  • key — строка или массив ключей перевода
  • options — объект параметров (интерполяция, контекст, множественное число и др.)
  • defaultValue — значение по умолчанию, если перевод не найден

При вызове t() происходит последовательный поиск значения в ресурсах текущего языка. Если ключ не найден, применяется fallback-язык или defaultValue.

Простейший сценарий использования

i18next.init({
  lng: 'ru',
  resources: {
    ru: {
      translation: {
        welcome: 'Добро пожаловать'
      }
    }
  }
});

i18next.t('welcome');

Механизм поиска работает по следующей цепочке:

  1. Поиск ключа в текущем языке (lng)
  2. Поиск в fallback-языке
  3. Возврат defaultValue, если указан
  4. Возврат ключа как строки, если ничего не найдено

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

Одна из ключевых возможностей t() — подстановка динамических значений через интерполяцию.

i18next.init({
  interpolation: {
    escapeValue: false
  },
  resources: {
    ru: {
      translation: {
        greeting: 'Привет, {{name}}'
      }
    }
  }
});

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

Интерполяция поддерживает:

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

Настройки интерполяции

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

Параметр escapeValue критически важен при работе с HTML, так как предотвращает XSS-инъекции при выводе пользовательских данных.

Множественное число (pluralization)

Функция t() автоматически обрабатывает формы множественного числа в зависимости от языка.

i18next.init({
  lng: 'ru',
  resources: {
    ru: {
      translation: {
        item: 'предмет',
        item_plural: 'предмета',
        item_plural_2: 'предметов'
      }
    }
  }
});

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

Передача count активирует механизм выбора формы:

  • count = 1 → singular
  • count = 2-4 → few
  • count = 5+ → many

Внутренне i18next использует CLDR-правила языка для определения формы.

Контекстные формы

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

i18next.init({
  lng: 'ru',
  resources: {
    ru: {
      translation: {
        friend: 'друг',
        friend_female: 'подруга'
      }
    }
  }
});

i18next.t('friend', { context: 'female' });

Алгоритм разрешения:

  1. Проверка ключа с суффиксом _context
  2. Если не найден — базовый ключ
  3. Если не найден — fallback

Контекст может комбинироваться с множественным числом:

i18next.t('friend', { context: 'female', count: 3 });

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

t() поддерживает разделение переводов на namespaces:

i18next.init({
  lng: 'ru',
  ns: ['common', 'dashboard'],
  defaultNS: 'common',
  resources: {
    ru: {
      common: {
        save: 'Сохранить'
      },
      dashboard: {
        title: 'Панель управления'
      }
    }
  }
});

i18next.t('save'); // common.save
i18next.t('dashboard:title');

Namespaces уменьшают конфликт ключей и повышают модульность словарей.

Опция defaultValue

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

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

Поведение:

  • при отсутствии перевода возвращается defaultValue
  • если defaultValue не задан, возвращается ключ

Вложенные ключи и структура данных

t() поддерживает вложенные структуры:

resources: {
  ru: {
    translation: {
      user: {
        profile: {
          title: 'Профиль пользователя'
        }
      }
    }
  }
}

Вызов:

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

Разделитель по умолчанию — точка, но может быть изменён:

keySeparator: '.'

Возврат объектов (returnObjects)

t() может возвращать не только строки, но и объекты:

i18next.init({
  returnObjects: true,
  resources: {
    ru: {
      translation: {
        menu: {
          home: 'Главная',
          about: 'О нас'
        }
      }
    }
  }
});

i18next.t('menu');

Результат:

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

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

Префиксы ключей (keyPrefix)

Для сокращения повторяющихся путей используется keyPrefix:

i18next.t('title', { keyPrefix: 'user.profile' });

Эквивалент:

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

Префикс применяется до поиска ключа и может комбинироваться с namespace.

Нестинг переводов (nesting)

t() поддерживает вложенные ссылки на другие ключи:

resources: {
  ru: {
    translation: {
      error: 'Ошибка',
      error_message: '{{error}}: что-то пошло не так'
    }
  }
}
i18next.t('error_message');

Результат:

Ошибка: что-то пошло не так

Нестинг работает рекурсивно, но ограничивается глубиной, чтобы избежать циклов.

Форматирование значений

t() может использовать кастомные форматтеры:

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

i18next.t('key', { value: 'text', format: 'uppercase' });

Форматирование применяется после интерполяции.

Функциональные ключи

В некоторых конфигурациях ключ может быть функцией:

i18next.t(() => 'dynamic.key');

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

Поведение при отсутствии ключа

Если ключ отсутствует:

  1. Проверяется fallback язык
  2. Проверяется defaultValue
  3. Возвращается ключ как строка
  4. При debug-режиме выводится предупреждение
i18next.init({
  debug: true
});

Обработка массивов ключей

t() принимает массив ключей для последовательного поиска:

i18next.t(['missing.key', 'fallback.key', 'default']);

Алгоритм:

  • возвращается первое найденное значение
  • если ничего не найдено — последний элемент массива

Локаль и динамическое переключение

t() всегда зависит от текущего языка:

i18next.changeLanguage('en');
i18next.t('welcome');

При смене языка происходит:

  • переразрешение ресурсов
  • обновление кеша
  • повторный доступ к ключам через t()

Влияние параметров lng и ns в options

t() позволяет переопределять язык и namespace локально:

i18next.t('welcome', { lng: 'en' });
i18next.t('save', { ns: 'dashboard' });

Это полезно для смешанных интерфейсов и админ-панелей.

Кеширование и оптимизация

t() оптимизирована через внутренний кеш разрешённых ключей:

  • кешируется результат поиска
  • кеш сбрасывается при смене языка
  • используется быстрый lookup по структуре JSON

При большом количестве переводов критично:

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

Комбинированные возможности

t() может одновременно использовать:

  • интерполяцию
  • pluralization
  • context
  • namespace
  • fallback
  • nesting

Пример комбинированного вызова:

i18next.t('notification', {
  context: 'email',
  count: 3,
  name: 'Ivan'
});

Такая комбинация приводит к выбору ключа по приоритету:

  1. namespace + context + plural
  2. namespace + context
  3. namespace + plural
  4. базовый ключ

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

Оглавление