Debug режим и логирование

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

Активация debug-режима

Основной способ включения debug-режима — передача параметра debug при инициализации:

import i18n from 'i18next';

i18n.init({
  debug: true,
  lng: 'en',
  fallbackLng: 'ru',
  resources: {
    en: {
      translation: {
        welcome: "Welcome"
      }
    }
  }
});

При активированном режиме библиотека начинает выводить подробную информацию в консоль. Это включает:

  • загрузку ресурсов;
  • выбор языка;
  • обработку fallback;
  • отсутствие ключей;
  • работу интерполяции;
  • состояние namespace.

Внутренняя модель логирования

Логирование в i18next основано на абстракции logger. По умолчанию используется консольный логгер, который пишет сообщения в console.

Уровни логирования:

  • debug — детальная отладочная информация;
  • info — общие информационные сообщения;
  • warn — предупреждения о потенциальных проблемах;
  • error — критические ошибки выполнения.

Пример типичного сообщения:

i18next: languageChanged en
i18next: initialized {
  lng: "en",
  fallbackLng: "ru"
}

Контроль уровней логирования

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

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

В этом случае будут отображаться только предупреждения и ошибки, тогда как debug- и info-сообщения подавляются.

Допустимые значения:

  • debug
  • info
  • warn
  • error

Отключение логирования

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

1. Через debug

i18n.init({
  debug: false
});

2. Через уровень логирования

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

В этом случае остаются только критические ошибки, связанные с выполнением.

Переназначение логгера

i18next позволяет заменить стандартный механизм логирования на собственную реализацию. Это используется для интеграции с системами мониторинга (Sentry, Datadog, ELK и др.).

const customLogger = {
  type: 'logger',
  log: (args) => console.log('LOG:', args),
  warn: (args) => console.warn('WARN:', args),
  error: (args) => console.error('ERROR:', args)
};

i18n.init({
  debug: true,
  logger: customLogger
});

Такой подход позволяет централизовать обработку логов без привязки к консоли браузера или Node.js.

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

Одной из ключевых функций debug-режима является отслеживание отсутствующих переводов.

Пример поведения:

i18n.t('missing_key_example');

В debug-режиме появится сообщение:

i18next::translator: missingKey en translation missing_key_example missing_key_example

Это позволяет выявлять:

  • непокрытые переводы;
  • ошибки в именовании ключей;
  • проблемы синхронизации ресурсов.

saveMissing и логирование пропусков

Дополнительный механизм — опция saveMissing, которая фиксирует отсутствующие ключи:

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

В этом режиме i18next не только сообщает об отсутствии ключа, но и может отправлять его во внешний backend.

Логирование загрузки ресурсов

При подключении backend-плагинов (например, HTTP backend) debug-режим отслеживает процесс загрузки переводов:

i18next: loaded namespace translation for language en
i18next: backendConnector: loaded namespace translation for language en

Это особенно важно при:

  • асинхронной загрузке переводов;
  • использовании CDN;
  • динамической подгрузке namespaces.

Поведение при ошибках интерполяции

Debug-режим фиксирует ошибки подстановки переменных:

i18n.t('welcome_user', { user: undefined });

Сообщение:

i18next: interpolation value for "user" is undefined

Такие сообщения позволяют выявлять:

  • некорректные данные;
  • отсутствие параметров;
  • ошибки API.

Взаимодействие с namespace логированием

При использовании нескольких namespace логирование помогает отслеживать, какой именно набор ресурсов был задействован:

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

В debug-режиме отображается:

i18next: initialized namespaces: common, auth, dashboard

Поведение в production-сборке

В production-среде debug-режим обычно отключается, поскольку:

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

Типичная конфигурация:

i18n.init({
  debug: process.env.NODE_ENV !== 'production',
  logLevel: process.env.NODE_ENV === 'production' ? 'error' : 'debug'
});

Интеграция с внешними системами логирования

Логгер i18next может быть адаптирован под централизованные системы:

const logger = {
  error: (msg) => sendToSentry(msg),
  warn: (msg) => sendToMonitoring(msg),
  log: () => {},
};

Это позволяет:

  • собирать статистику отсутствующих ключей;
  • отслеживать деградации переводов;
  • фиксировать ошибки загрузки ресурсов;
  • анализировать поведение пользователей через локализацию.

Особенности поведения debug в разных окружениях

Браузер

  • вывод в console;
  • группировка сообщений;
  • поддержка цветового форматирования (в зависимости от браузера).

Node.js

  • потоковый вывод в stdout;
  • отсутствие группировки по умолчанию;
  • интеграция с логгерами уровня приложения.

Частые категории диагностических сообщений

Debug-вывод i18next можно условно разделить:

Инициализация

  • загрузка конфигурации;
  • установка языка;
  • определение fallback.

Ресурсы

  • загрузка translation bundles;
  • кеширование;
  • ошибки backend.

Переводы

  • missingKey;
  • fallback chain;
  • interpolation issues.

Система

  • регистрация плагинов;
  • подключение middleware;
  • изменение языка в runtime.
Оглавление