Архитектура плагинов i18next

В основе i18next лежит строго модульная архитектура, в которой ядро библиотеки выполняет роль координатора, а вся функциональность, зависящая от среды выполнения или специфики проекта, выносится в подключаемые плагины. Такая структура позволяет использовать i18next как в браузере, так и в Node.js, React Native или на серверных рендерах без изменения основного кода.

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

Базовая модель плагинов

Плагин в i18next — это объект или функция, реализующая контракт через метод init и регистрируемая в ядре через i18next.use().

Общий принцип выглядит следующим образом:

  • ядро хранит список подключённых модулей;
  • каждый модуль получает доступ к экземпляру i18n;
  • модуль расширяет функциональность через хук инициализации;
  • жизненный цикл плагина синхронизируется с i18next.init().

Типичная регистрация:

import i18n from 'i18next';

i18n
  .use(plugin)
  .init(options);

Метод use() не выполняет немедленную инициализацию. Он только добавляет плагин в очередь, которая обрабатывается при запуске init().

Внутренний цикл инициализации

Архитектура инициализации строится вокруг последовательного подключения модулей:

  1. Создание экземпляра i18n
  2. Регистрация плагинов через use()
  3. Вызов init()
  4. Инициализация каждого плагина
  5. Загрузка ресурсов переводов
  6. Установка языка
  7. Активация middleware и подписчиков

Каждый плагин получает ссылку на основной объект:

plugin.init(i18n, options);

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

Типы плагинов в экосистеме i18next

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

Backend-плагины

Backend отвечает за загрузку переводов из внешних источников: файловой системы, HTTP, базы данных.

Контракт backend-плагина:

  • read(language, namespace, callback)
  • create() (опционально)
  • init() (опционально)

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

backend.read('en', 'common', (err, data) => {
  // загрузка ресурсов переводов
});

Backend подключается как стандартный модуль:

i18n.use(BackendPlugin);

Архитектурно backend отделён от ядра, что позволяет заменять источник данных без изменения логики интерполяции и работы с языками.

Language Detector

Модуль определения языка отвечает за выбор активной локали пользователя.

Поддерживаемые источники:

  • cookie
  • localStorage
  • navigator (браузер)
  • headers (сервер)
  • query string

Контракт детектора:

  • lookup(options)
  • cacheUserLanguage(lng, options)

Пример:

detector.lookup = function(options) {
  return window.localStorage.getItem('lng');
};

Этот плагин особенно важен в SSR-архитектурах, где язык определяется на основе HTTP-заголовков.

Post-Processors

PostProcessor позволяет изменять уже переведённую строку после выполнения интерполяции.

Интерфейс:

  • name
  • process(value, key, options, translator)

Пример логики:

postProcessor.process = function(value) {
  return value.toUpperCase();
};

Архитектурно этот слой располагается после всех операций перевода и интерполяции, но до возврата результата в приложение.

Formatter-плагины

Форматтеры отвечают за локализованное форматирование значений: даты, числа, валюты.

В новых версиях i18next часто делегирует форматирование Intl API, но архитектурно поддерживается расширение через кастомные форматтеры.

Форматтер получает:

  • значение
  • формат
  • язык

Cache и persistence плагины

Эти модули отвечают за хранение состояния:

  • кэш переводов
  • сохранение выбранного языка
  • оптимизация повторных запросов

Типичный сценарий — сохранение языка пользователя:

cache.save('lng', 'en');

Кэширование особенно важно в браузерных приложениях с динамической подгрузкой namespaces.

Внутренняя регистрация плагинов

Все плагины проходят через единый механизм регистрации:

i18n.use = function(module) {
  modules.push(module);
  return i18n;
};

При init() происходит обход массива:

modules.forEach(m => {
  if (typeof m.init === 'function') {
    m.init(i18n, options[m.type]);
  }
});

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

Слои архитектуры выполнения перевода

Процесс перевода в i18next можно представить как последовательность слоёв:

  1. API слой (t() функция)
  2. Translator
  3. Resource Store
  4. Backend загрузчик
  5. PostProcessor
  6. Formatter
  7. Return value

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

Resource Store как ядро данных

Resource Store — это внутренняя структура хранения переводов.

Она организована по принципу:

resources[language][namespace] = translations

Пример:

{
  en: {
    common: {
      hello: "Hello"
    }
  }
}

Backend плагины не взаимодействуют напрямую с UI-слоем. Они только наполняют store.

Поток данных при вызове t()

Вызов:

i18n.t('common:hello');

Проходит следующий путь:

  1. Парсинг ключа (namespace:key)
  2. Проверка текущего языка
  3. Поиск в Resource Store
  4. Если отсутствует — вызов backend
  5. Применение интерполяции
  6. Применение postProcessors
  7. Форматирование значений
  8. Возврат результата

Асинхронность и lazy loading плагинов

Backend плагины часто работают асинхронно. i18next поддерживает lazy loading namespaces:

  • загрузка только нужных переводов
  • подгрузка при первом обращении
  • кеширование результата

Механизм:

i18n.loadNamespaces('common', () => {
  // namespace готов
});

Архитектурно это снижает начальную нагрузку приложения.

Расширяемость через пользовательские плагины

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

  • кастомные источники переводов
  • специфические правила форматирования
  • интеграцию с API CMS
  • логирование переводов
  • A/B тестирование текстов

Пример кастомного плагина:

const customPlugin = {
  type: 'backend',
  init: function(services, options) {},
  read: function(language, namespace, callback) {
    fetch(`/api/translations/${language}/${namespace}`)
      .then(res => res.json())
      .then(data => callback(null, data));
  }
};

Взаимодействие плагинов с core services

Core services i18next включают:

  • languageUtils
  • pluralResolver
  • interpolator
  • resourceStore
  • logger

Плагины получают доступ к этим сервисам через init().

Важно, что архитектура не допускает замены core без форка библиотеки, но допускает расширение поведения через обёртки.

Порядок выполнения плагинов

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

  • сначала backend
  • затем languageDetector
  • затем cache
  • затем postProcessor

Порядок влияет на конечный результат перевода, особенно при наличии нескольких postProcessor-ов.

Middleware-архитектура в браузере и SSR

В SSR окружениях i18next интегрируется как middleware:

  • Express middleware
  • Next.js интеграция
  • React Suspense режим

Middleware получает доступ к req и res, что позволяет:

  • определять язык по заголовкам
  • подгружать переводы до рендера
  • предотвращать flickering контента

Слабая связность и контрактная модель

Ключевой принцип архитектуры — контрактность:

  • каждый плагин реализует минимальный интерфейс
  • ядро не знает реализацию плагина
  • взаимодействие происходит через services object
  • отсутствует прямой импорт между модулями

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

  • заменять backend без изменений кода приложения
  • добавлять детекторы языка под любые среды
  • внедрять кастомные форматы без модификации core

Ограничения архитектуры плагинов

Несмотря на гибкость, архитектура имеет ограничения:

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

Эти особенности компенсируются стабильностью core API и предсказуемым жизненным циклом.

Роль событийной модели

i18next использует события для синхронизации состояния:

  • initialized
  • loaded
  • languageChanged
  • missingKey

Плагины могут подписываться:

i18n.on('languageChanged', lng => {
  // реакция на смену языка
});

Это позволяет строить реактивные системы поверх ядра.

Интеграция плагинов в реактивные фреймворки

В React и Vue архитектура плагинов используется косвенно:

  • backend подгружает переводы
  • detector определяет язык
  • cache ускоряет ререндер
  • i18n instance передаётся через context

Плагины остаются вне UI-слоя, обеспечивая чистое разделение ответственности.

Оглавление