Концепция backend плагинов

Backend-плагины в i18next отвечают за получение, загрузку и, в некоторых сценариях, создание переводов из внешних источников. Основная идея заключается в разделении ответственности: ядро i18next управляет интернационализацией, а backend-слой определяет способ доставки языковых ресурсов.

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

Базовая модель загрузки ресурсов

i18next оперирует структурой ресурсов следующего вида:

  • язык (lng)
  • пространство имён (namespace)
  • ключи переводов

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

{
  "ru": {
    "translation": {
      "welcome": "Добро пожаловать"
    }
  }
}

Backend-плагин участвует в процессе, когда требуется:

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

Интерфейс backend-плагина

Любой backend для i18next реализует строго определённый контракт. Наиболее часто используются методы:

  • read(language, namespace, callback)
  • readMulti(languages, namespaces, callback)
  • create(languages, namespace, key, fallbackValue)
  • init(services, backendOptions, i18nextOptions)
  • type (идентификация backend)

Минимальная форма:

class CustomBackend {
  constructor(services, options = {}) {
    this.init(services, options);
  }

  init(services, options = {}, i18nextOptions = {}) {
    this.services = services;
    this.options = options;
    this.i18nextOptions = i18nextOptions;
  }

  read(language, namespace, callback) {
    callback(null, {});
  }
}

Метод read является ключевым: именно он возвращает набор переводов для конкретного языка и namespace.

Файловый backend как эталон реализации

Одним из наиболее распространённых решений является файловый backend для Node.js. Он используется в серверных приложениях, где доступна файловая система.

Типичная реализация:

import Backend from "i18next-fs-backend";

i18next
  .use(Backend)
  .init({
    lng: "ru",
    fallbackLng: "en",
    backend: {
      loadPath: "./locales/{{lng}}/{{ns}}.json"
    }
  });

Механика работы

  • формируется путь к файлу
  • файл читается синхронно или асинхронно
  • JSON парсится в объект ресурсов
  • данные кешируются внутри i18next

Шаблоны путей позволяют динамически формировать структуру:

./locales/en/translation.json
./locales/ru/translation.json

HTTP backend для браузера

В клиентских приложениях используется HTTP backend, который загружает переводы с удалённого сервера.

import HttpBackend from "i18next-http-backend";

i18next
  .use(HttpBackend)
  .init({
    backend: {
      loadPath: "https://example.com/locales/{{lng}}/{{ns}}.json"
    }
  });

Особенности работы в браузере

  • загрузка асинхронная
  • используется fetch или XMLHttpRequest
  • возможны CORS-ограничения
  • важна стратегия кеширования

Множественная загрузка ресурсов

Backend может поддерживать массовую загрузку:

readMulti(languages, namespaces, callback)

Пример вызова:

backend.readMulti(
  ["en", "ru"],
  ["translation", "common"],
  (err, data) => {}
);

Это снижает количество запросов и оптимизирует старт приложения.

Жизненный цикл backend-плагина

Backend интегрируется в систему i18next через последовательность этапов:

  1. Инициализация через .use()
  2. Вызов init()
  3. Регистрация сервисов i18next
  4. Запрос ресурсов при первом обращении
  5. Кеширование загруженных данных
  6. Обновление при необходимости

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

Встроенные и кастомные backend-реализации часто используют кеширование:

  • память процесса (in-memory cache)
  • HTTP-cache заголовки
  • локальное хранилище (в браузере)
  • CDN-уровень

В i18next кеширование происходит на уровне:

  • языка
  • namespace
  • комбинации языка и namespace

Ленивое (lazy) подгружение namespaces

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

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

i18next.init({
  ns: ["common"],
  defaultNS: "common",
  partialBundledLanguages: true,
  backend: {
    loadPath: "/locales/{{lng}}/{{ns}}.json"
  }
});

При запросе ключа из другого namespace backend автоматически инициирует загрузку.

Создание переводов через backend

Некоторые backend-реализации поддерживают запись переводов:

create(languages, namespace, key, fallbackValue)

Сценарии применения:

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

Пример:

backend.create("ru", "translation", "new_key", "Значение по умолчанию");

Собственный backend-плагин

Создание кастомного backend необходимо при нестандартных источниках данных.

Пример backend для API

class ApiBackend {
  init(services, options) {
    this.apiUrl = options.apiUrl;
  }

  read(language, namespace, callback) {
    fetch(`${this.apiUrl}/${language}/${namespace}`)
      .then(res => res.json())
      .then(data => callback(null, data))
      .catch(err => callback(err, null));
  }
}

Подключение кастомного backend

i18next
  .use(ApiBackend)
  .init({
    backend: {
      apiUrl: "https://api.example.com/locales"
    }
  });

Обработка ошибок загрузки

Backend обязан корректно обрабатывать ситуации:

  • отсутствующий файл
  • недоступный сервер
  • некорректный JSON
  • таймаут запроса

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

read(language, namespace, callback) {
  try {
    const data = loadFromSource();
    callback(null, data);
  } catch (e) {
    callback(e, null);
  }
}

i18next при ошибке может использовать:

  • fallback language
  • пустой объект
  • ранее кешированные данные

Fallback-цепочки и backend

Backend тесно связан с системой fallback-языков.

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

i18next.init({
  fallbackLng: ["en", "de"],
});

При отсутствии перевода:

  1. запрашивается основной язык
  2. затем fallback язык
  3. затем дефолтный namespace

Backend участвует в каждом этапе загрузки.

Многоуровневая архитектура backend

В сложных приложениях backend может быть составным:

  • файловый источник для базовых переводов
  • API для динамических изменений
  • кеш-слой Redis
  • CDN для ускоренной доставки

Такая архитектура реализуется через обёртки:

class CompositeBackend {
  constructor(backends) {
    this.backends = backends;
  }

  read(language, namespace, callback) {
    // попытка последовательно из разных источников
  }
}

Взаимодействие backend и интерполяции

Backend не занимается интерполяцией напрямую, но влияет на структуру данных, которая будет обработана i18next.

Пример:

{
  "greeting": "Привет, {{name}}"
}

Backend возвращает строку, а подстановка выполняется позже в core-слое.

Namespace как ключевая единица загрузки

Backend всегда оперирует связкой:

  • language + namespace

Namespace позволяет:

  • разделять модули приложения
  • загружать только нужные переводы
  • уменьшать размер initial bundle

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

locales/
  ru/
    auth.json
    dashboard.json

Производственные сценарии использования backend

Backend-плагины используются в различных типах приложений:

  • SSR-приложения на Node.js
  • SPA на React/Vue
  • мобильные webview-приложения
  • микросервисные архитектуры с централизованной локализацией

Каждый сценарий диктует выбор backend-стратегии:

  • файловый backend для серверов
  • HTTP backend для клиентских приложений
  • API backend для централизованных систем

Производительность и масштабирование

Ключевые факторы производительности:

  • количество HTTP-запросов
  • размер переводов
  • стратегия кеширования
  • параллельная загрузка namespaces

Оптимизация достигается через:

  • bundling переводов
  • CDN
  • gzip/brotli сжатие
  • предварительную загрузку (preload languages)

Безопасность backend-слоя

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

  • утечка переводов через публичные API
  • отсутствие контроля доступа
  • отсутствие валидации данных

Типичные меры:

  • токены доступа к API
  • ограничение namespaces
  • подписанные запросы
  • серверная фильтрация языков
Оглавление