Режим разработки vs продакшн

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

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

import i18n from "i18next";

i18n.init({
  debug: true,
  fallbackLng: "en",
  interpolation: {
    escapeValue: false
  }
});

При debug: true библиотека начинает активно логировать:

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

Поведение отсутствующих ключей

В разработке отсутствующие ключи не должны оставаться незамеченными. Типичное поведение:

  • вывод предупреждения в консоль;
  • возврат самого ключа (или fallback-значения);
  • возможность включения saveMissing для сбора недостающих переводов.
i18n.init({
  debug: true,
  saveMissing: true,
  missingKeyHandler: (lng, ns, key) => {
    console.warn(`Missing key: ${key} [${lng}:${ns}]`);
  }
});

В таком режиме система может использоваться как инструмент аудита локализации, позволяя выявлять «дыры» в переводах прямо во время разработки интерфейса.

Загрузка ресурсов и гибкость

В режиме разработки часто отключается агрессивное кэширование. Это позволяет мгновенно видеть изменения в JSON-файлах переводов.

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

import Backend from "i18next-http-backend";

i18n.use(Backend).init({
  debug: true,
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json",
    requestOptions: {
      cache: "no-store"
    }
  }
});

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

Особенности интерполяции

В режиме разработки интерполяция часто настраивается более мягко, чтобы ошибки не блокировали интерфейс:

interpolation: {
  escapeValue: false,
  skipOnVariables: false
}

При этом удобно включать логирование некорректных данных, например undefined или null в шаблонах.

Продакшн-режим

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

Отключение debug и логов

Главное правило — отсутствие диагностического шума:

i18n.init({
  debug: false,
  fallbackLng: "en"
});

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

Оптимизация загрузки переводов

В продакшне критично минимизировать количество запросов и размер загружаемых файлов.

Часто используются:

  • CDN для статических JSON-файлов;
  • gzip/brotli-сжатие;
  • агрегация namespace-файлов;
  • кеширование на уровне браузера.
backend: {
  loadPath: "https://cdn.example.com/locales/{{lng}}/{{ns}}.json",
  crossDomain: true,
  withCredentials: false
}

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

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

  • HTTP cache headers (Cache-Control);
  • service worker;
  • memory cache внутри i18next;
  • локальное хранилище (в некоторых стратегиях).

Дополнительно может использоваться i18next-chained-backend, где сначала проверяется кэш, затем сеть.

Критические различия между режимами

Логирование

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

Работа с отсутствующими ключами

  • Разработка: предупреждения, fallback + диагностика
  • Продакшн: тихий fallback без уведомлений

Загрузка ресурсов

  • Разработка: частая перезагрузка JSON, отсутствие кэширования
  • Продакшн: агрессивное кэширование и CDN

Производительность

  • Разработка: приоритет удобству отладки
  • Продакшн: приоритет скорости рендера и минимального TTI

Управление через NODE_ENV

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

i18n.init({
  debug: process.env.NODE_ENV !== "production",
  saveMissing: process.env.NODE_ENV !== "production"
});

Такой подход обеспечивает синхронизацию поведения с общими практиками сборки (Webpack, Vite, Next.js).

Tree-shaking и сборка

В продакшне важен контроль за размером бандла. i18next поддерживает модульную архитектуру, что позволяет:

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

Пример ленивой загрузки:

i18n.loadNamespaces(["common", "auth"]);

В сочетании с code splitting это снижает первоначальную нагрузку на приложение.

Стратегии отладки в продакшне

Хотя продакшн-режим предполагает минимизацию логов, иногда включают ограниченную диагностику:

  • выборочное логирование ошибок;
  • отправка missing keys в аналитическую систему;
  • feature flag для debug mode.
i18n.init({
  debug: false,
  saveMissing: true,
  missingKeyHandler: (lng, ns, key) => {
    fetch("/log-missing-key", {
      method: "POST",
      body: JSON.stringify({ lng, ns, key })
    });
  }
});

Поведение fallback-цепочек

В обоих режимах сохраняется логика fallback, но в продакшне она должна быть стабильной и предсказуемой.

fallbackLng: ["en", "ru"]

Разница заключается в том, что в разработке fallback сопровождается предупреждениями, а в продакшне — нет.

Разделение конфигураций

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

const isDev = process.env.NODE_ENV !== "production";

export const i18nConfig = {
  debug: isDev,
  fallbackLng: "en",
  saveMissing: isDev,
  backend: {
    loadPath: isDev
      ? "/locales/{{lng}}/{{ns}}.json"
      : "https://cdn.example.com/locales/{{lng}}/{{ns}}.json"
  }
};

CDN и продакшн-доставка переводов

Использование CDN является стандартной практикой:

  • уменьшение задержки загрузки;
  • географическое распределение;
  • снижение нагрузки на backend.

При этом важно поддерживать версионирование:

/locales/v3/en/common.json

Это предотвращает проблемы с кэшированием при обновлении переводов.

Поведение при ошибках загрузки

Разработка:

  • подробные stacktrace;
  • повторные попытки загрузки;
  • логирование в консоль.

Продакшн:

  • тихий fallback;
  • fallback-язык;
  • минимизация пользовательского воздействия.

Интерполяция и безопасность

В продакшне критично исключать XSS-риски. i18next использует экранирование значений интерполяции по умолчанию, но при escapeValue: false ответственность переносится на разработчика.

interpolation: {
  escapeValue: true
}

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

Итоговая модель поведения системы

Разделение режимов фактически формирует два разных уровня работы:

  • разработка — диагностика, прозрачность, гибкость;
  • продакшн — скорость, стабильность, минимальный overhead.

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

Оглавление