Дебаггинг переводов

В библиотеке i18next механизм отладки является центральным инструментом при анализе проблем интернационализации. Основной источник информации — логирование внутренних процессов загрузки ресурсов, поиска ключей, выбора fallback-языков и применения интерполяции.

Активация режима выполняется через параметр конфигурации:

i18next.init({
  debug: true,
  lng: 'ru',
  fallbackLng: 'en',
  resources: {
    ru: {
      translation: {
        greeting: "Привет"
      }
    }
  }
});

При включённом режиме система выводит подробные сообщения о каждом этапе обработки ключей перевода: загрузка namespace, выбор языка, отсутствие ключей, использование fallback-цепочек.

Ключевой аспект режима отладки — прозрачность цепочки разрешения перевода. При запросе строки сначала определяется активный язык, затем проверяется наличие ключа в соответствующем namespace. В случае отсутствия выполняется переход к fallback-языкам.

Логирование отсутствующих ключей

Одной из наиболее частых проблем является отсутствие переводов. i18next фиксирует такие случаи и выводит предупреждения в консоль.

Типичный сценарий:

i18next.t('button.submit');

При отсутствии ключа в текущем языке лог содержит информацию вида:

i18next::translator: missingKey en translation button.submit button.submit

В сообщении присутствуют:

  • язык, в котором произошёл поиск
  • namespace
  • ключ
  • значение по умолчанию (если используется)

Интерпретация missingKey

Отсутствие ключа не всегда означает ошибку конфигурации. Возможны следующие причины:

  • ключ не добавлен в ресурсный файл
  • неверно указан namespace
  • ошибка в структуре JSON переводов
  • динамический ключ формируется некорректно
  • используется другой язык, чем ожидается

Namespace как источник скрытых ошибок

Архитектура i18next основана на разделении переводов на namespaces. При неверной конфигурации загрузки ресурсов ключи оказываются недоступными, несмотря на их фактическое наличие.

Пример структуры:

i18next.init({
  ns: ['common', 'auth'],
  defaultNS: 'common',
  resources: {
    en: {
      common: {
        ok: "OK"
      },
      auth: {
        login: "Login"
      }
    }
  }
});

Типичная проблема возникает при обращении без указания namespace:

i18next.t('login');

Поиск выполняется в common, где ключ отсутствует, что приводит к fallback или missingKey.

Логирование помогает определить, в каком namespace выполнялся поиск и на каком этапе произошёл сбой разрешения ключа.

Отладка загрузки ресурсов

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

Пример конфигурации с backend:

import Backend from 'i18next-http-backend';

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

В режиме отладки фиксируются следующие этапы:

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

Типичные проблемы:

  • неверный путь loadPath
  • отсутствие файла перевода
  • CORS-ограничения
  • некорректный JSON (ошибка парсинга)

При ошибке загрузки библиотека переключается на fallback-язык, что также отражается в логах.

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

i18next поддерживает интерполяцию значений:

i18next.t('welcome_user', { name: 'Alex' });

Перевод:

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

Частые проблемы интерполяции

В режиме отладки фиксируются ситуации:

  • отсутствующий параметр
  • несоответствие имени переменной
  • экранирование символов
  • конфликт синтаксиса

Пример ошибки:

i18next.t('welcome_user');

Логически отсутствует name, что приводит к выводу:

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

При включённом debug дополнительно фиксируются предупреждения о непереданных интерполяционных значениях.

Проблемы с pluralization

Механизм множественных форм является одной из наиболее сложных частей системы перевода.

Пример конфигурации:

{
  "apple_one": "яблоко",
  "apple_other": "яблок"
}

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

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

В debug-режиме фиксируются:

  • выбранная форма (one, few, many, other)
  • используемые правила языка
  • отсутствие нужной формы

Типовые ошибки:

  • отсутствие count в параметрах
  • неполный набор форм
  • некорректные правила языка

При отсутствии корректной формы происходит fallback к other, что также отображается в логах.

Fallback-цепочки и их диагностика

Fallback-языки формируют цепочку поиска ключей:

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

Алгоритм поиска:

  1. текущий язык
  2. первый fallback
  3. следующий fallback
  4. default language

В debug-режиме фиксируется переход между языками:

i18next::translator: key "submit" not found in ru
i18next::translator: key "submit" not found in uk
i18next::translator: using fallback en

Основные причины частых переходов:

  • неполные переводы в основном языке
  • несинхронизированные ресурсы
  • некорректная загрузка namespaces

Кастомное логирование и обработка ошибок

Стандартный механизм логирования может быть расширен через logger.

i18next
  .init({
    debug: true,
    logger: {
      type: 'logger',
      log: (args) => console.log(args),
      warn: (args) => console.warn(args),
      error: (args) => console.error(args)
    }
  });

Дополнительно возможно подключение перехвата отсутствующих ключей:

i18next.on('missingKey', (lngs, namespace, key) => {
  console.log(lngs, namespace, key);
});

Такая обработка используется для:

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

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

Механизм saveMissing позволяет фиксировать и отправлять отсутствующие переводы на сервер:

i18next.init({
  saveMissing: true,
  missingKeyHandler: (lng, ns, key) => {
    // отправка на backend
  }
});

В debug-режиме фиксируется:

  • факт отсутствия ключа
  • язык
  • namespace
  • контекст вызова

Основные сценарии использования:

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

Ошибки синхронизации состояния языка

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

i18next.changeLanguage('en');

Возможные проблемы:

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

Debug-лог фиксирует этапы:

  • начало смены языка
  • загрузка ресурсов
  • завершение переключения
  • обновление внутренних кэшей

Диагностика кэширования переводов

i18next активно использует кеширование ресурсов. При разработке это может скрывать изменения в JSON-файлах переводов.

Типичные признаки:

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

В debug-режиме можно наблюдать:

i18next::backendConnector: loaded namespace translation for en
i18next::cache: key already exists, skipping load

Проблемные зоны:

  • браузерный кеш
  • service worker
  • внутренний cache backend-плагина

Конфликты ключей и неоднозначные разрешения

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

{
  "button": {
    "submit": "Отправить"
  },
  "button.submit": "Отправить"
}

Поведение зависит от конфигурации keySeparator.

i18next.init({
  keySeparator: '.'
});

В debug-режиме фиксируются:

  • интерпретация пути ключа
  • столкновения flat и nested структур
  • фактический выбранный вариант

Обработка форматирования и постобработки

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

i18next.t('price', { postProcess: 'currency' });

Ошибки возникают при:

  • отсутствии postProcessor
  • неправильной регистрации плагина
  • конфликте форматов

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

postProcessor: currency applied

или сообщение об отсутствии обработчика.

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

Совокупность debug-инструментов i18next формирует многоуровневую систему анализа:

  • разрешение ключа
  • выбор языка
  • загрузка ресурсов
  • применение интерполяции
  • обработка pluralization
  • постобработка
  • fallback-цепочка

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

Оглавление