Конфигурация путей и endpoints

Архитектура загрузки переводов в i18next строится вокруг гибкой системы источников ресурсов и правил их разрешения. В отличие от статических решений, i18next допускает динамическую подгрузку переводов через HTTP, файловые системы (в Node.js), кастомные backend-плагины и собственные обработчики запросов. Центральное место занимает конфигурация путей (loadPath) и endpoints, определяющих, откуда и каким образом будут получены языковые ресурсы.

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

i18next разделяет процесс получения переводов на несколько уровней:

  • определение языка (language detection)
  • формирование ключа ресурса (namespace + language)
  • построение URL или пути к файлу
  • выполнение запроса к backend
  • кэширование результата

Ключевым элементом выступает backend-слой, который отвечает за взаимодействие с источником данных.

Конфигурация backend и loadPath

Наиболее распространённый сценарий — использование HTTP backend через i18next-http-backend. В этом случае конфигурация путей задаётся через шаблон loadPath.

import i18next from "i18next";
import HttpBackend from "i18next-http-backend";

i18next
  .use(HttpBackend)
  .init({
    lng: "en",
    fallbackLng: "ru",
    ns: ["common", "auth"],
    defaultNS: "common",
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json"
    }
  });

Шаблонные параметры loadPath

В строке пути используются переменные:

  • {{lng}} — код языка (en, ru, de)
  • {{ns}} — namespace (common, auth, dashboard)
  • {{nsSeparator}} и {{keySeparator}} применяются в специфических сценариях
  • дополнительные кастомные параметры могут быть внедрены через queryStringParameters

Пример итогового запроса:

/locales/ru/common.json
/locales/en/auth.json

Конфигурация endpoints в HTTP backend

При работе через HTTP backend endpoint определяется как базовый URL, к которому добавляется loadPath. В ряде архитектур используется разделение:

  • API endpoint (backend сервер)
  • static endpoint (CDN или файловое хранилище)
  • fallback endpoint (резервный источник переводов)

Базовый endpoint через loadPath

backend: {
  loadPath: "https://cdn.example.com/i18n/{{lng}}/{{ns}}.json"
}

Здесь endpoint фактически встроен в путь, что делает конфигурацию простой, но менее гибкой.

Разделение API endpoint и ресурсного пути

В более сложных системах endpoint отделяется от логики формирования пути.

const API_BASE = "https://api.example.com";

backend: {
  loadPath: `${API_BASE}/translations/{{lng}}/{{ns}}`,
  addPath: `${API_BASE}/translations`,
  allowMultiLoading: true
}

Назначение ключевых endpoints

  • loadPath — получение переводов
  • addPath — отправка новых ключей (в системах с динамической локализацией)
  • read и write endpoints в кастомных backend-плагинах

Кастомизация HTTP запросов

Для контроля над endpoint-запросами используется функция requestOptions.

backend: {
  loadPath: "/api/i18n/{{lng}}/{{ns}}",
  requestOptions: {
    method: "GET",
    credentials: "include",
    headers: {
      "Authorization": "Bearer TOKEN",
      "Content-Type": "application/json"
    }
  }
}

Такая конфигурация позволяет интегрировать i18next с защищёнными API, где endpoint требует авторизации.

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

В некоторых архитектурах переводимые ресурсы не хранятся в статических JSON-файлах, а генерируются динамически через API.

backend: {
  loadPath: "/api/translations",
  queryStringParams: {
    lang: "{{lng}}",
    namespace: "{{ns}}",
    version: "1.0"
  }
}

Фактический endpoint будет выглядеть так:

/api/translations?lang=ru&namespace=common&version=1.0

Многоуровневая система endpoints

В продакшн-архитектурах часто применяется каскадная схема:

  1. CDN endpoint (быстрый доступ)
  2. API endpoint (актуальные данные)
  3. локальный fallback (вшитые ресурсы)

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

backend: {
  loadPath: [
    "https://cdn.example.com/i18n/{{lng}}/{{ns}}.json",
    "https://api.example.com/i18n/{{lng}}/{{ns}}"
  ]
}

Если первый endpoint недоступен, выполняется переход ко второму.

Кэширование и взаимодействие с endpoint

i18next не реализует кэш самостоятельно, но работает в связке с backend-слоем или браузерным кэшем.

backend: {
  loadPath: "/locales/{{lng}}/{{ns}}.json",
  allowMultiLoading: true,
  crossDomain: true
}

Влияние на endpoint:

  • crossDomain: true активирует CORS-запросы
  • allowMultiLoading уменьшает количество обращений к endpoint за счёт пакетной загрузки namespaces

Версионирование endpoint

Для управления изменениями переводов применяется версионирование URL.

backend: {
  loadPath: "/i18n/v2/{{lng}}/{{ns}}.json"
}

или через query:

/i18n/{{lng}}/{{ns}}.json?v=2

Версионирование обеспечивает:

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

Динамическое формирование endpoint

В некоторых системах endpoint вычисляется программно.

backend: {
  loadPath: (lng, ns) => {
    if (lng === "ru") {
      return `/ru-api/${ns}`;
    }
    return `/global-api/${lng}/${ns}`;
  }
}

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

  • мультирегиональных системах
  • разделении языковых кластеров
  • интеграции с несколькими backend-сервисами

Endpoint и namespaces

Namespaces напрямую влияют на структуру endpoint-запросов. При использовании нескольких namespaces i18next формирует отдельные обращения или агрегирует их.

ns: ["common", "dashboard", "errors"],
defaultNS: "common"

Запросы к endpoint:

/locales/ru/common.json
/locales/ru/dashboard.json
/locales/ru/errors.json

или при мультизагрузке:

/locales/ru/{common,dashboard,errors}.json

Обработка ошибок endpoint

При недоступности endpoint применяется fallback-цепочка:

  • fallbackLng
  • partial loading
  • empty resources
i18next.init({
  fallbackLng: "en",
  saveMissing: false
});

Если endpoint возвращает ошибку:

  • 404 — отсутствует файл перевода
  • 500 — ошибка backend
  • timeout — сетевой сбой

i18next переключается на резервный язык без прерывания работы приложения.

Безопасность endpoint

При работе с внешними endpoint важно учитывать:

  • CORS-политики
  • токены авторизации
  • ограничение доступа к namespace
  • защита от утечки локализационных данных

Пример безопасной конфигурации:

backend: {
  loadPath: "/api/i18n/{{lng}}/{{ns}}",
  requestOptions: {
    credentials: "same-origin",
    headers: {
      "X-Requested-With": "XMLHttpRequest"
    }
  }
}

CDN как endpoint уровня доставки

Использование CDN меняет роль endpoint с динамического API на статический ресурсный слой.

backend: {
  loadPath: "https://cdn.static-i18n.com/{{lng}}/{{ns}}.json"
}

Особенности:

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

Интеграция нескольких endpoint-источников

При сложных приложениях endpoint может быть распределён между несколькими провайдерами:

  • пользовательские переводы (API)
  • системные переводы (CDN)
  • экспериментальные фичи (feature flags API)

Логика объединения:

backend: {
  loadPath: [
    "/api/user-translations/{{lng}}/{{ns}}",
    "/cdn/system/{{lng}}/{{ns}}.json"
  ]
}

Результат объединяется в единый ресурсный объект, где приоритет зависит от порядка загрузки.

Оглавление