Философия и архитектурные принципы

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

Ключевая философия библиотеки основана на нескольких принципах:

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

В отличие от примитивных словарей вида:

const messages = {
  hello: "Привет"
}

архитектура I18next ориентирована на крупные приложения с десятками языков, сложными правилами склонений, lazy-loading переводов и разделением контента по модулям.

Архитектурная модель I18next

Внутренняя архитектура библиотеки строится вокруг нескольких базовых сущностей:

Сущность Назначение
resource store Хранилище переводов
language detector Определение языка
backend Загрузка переводов
namespace Логическое разделение переводов
translator Механизм поиска и обработки ключей
interpolator Подстановка переменных
plural resolver Обработка множественных форм

Главная идея — разделение ответственности между независимыми подсистемами.

Принцип независимости от UI-фреймворков

Одно из фундаментальных решений I18next — отсутствие привязки к конкретной платформе.

Библиотека может использоваться с:

  • Vanilla JavaScript;
  • React;
  • Vue;
  • Angular;
  • Svelte;
  • Node.js;
  • Electron;
  • Next.js;
  • React Native.

Ядро библиотеки остаётся одинаковым:

import i18next from "i18next"

i18next.init({
  lng: "ru",
  resources: {
    ru: {
      translation: {
        hello: "Привет"
      }
    }
  }
})

UI-интеграции существуют как отдельные адаптеры:

  • react-i18next
  • next-i18next
  • vue-i18next

Такой подход соответствует архитектурному принципу loose coupling — слабой связанности компонентов.

Принцип декларативности переводов

I18next использует декларативную модель локализации.

Вместо ручного выбора строк:

if (lang === "ru") {
  text = "Привет"
}

используются ключи:

t("greeting.hello")

Ключ становится стабильным идентификатором текста.

Это создаёт несколько преимуществ:

Независимость логики от контента

Код приложения не зависит от языка.

Упрощение рефакторинга

Текст можно изменять без изменения бизнес-логики.

Централизованное управление переводами

Все локализационные данные находятся в одном месте.

Resource Store как центральное хранилище

В основе I18next лежит resource store — объект, содержащий переводы.

Типичная структура:

{
  en: {
    translation: {
      common: {
        save: "Save"
      }
    }
  },
  ru: {
    translation: {
      common: {
        save: "Сохранить"
      }
    }
  }
}

Архитектурно это дерево:

language
  └── namespace
        └── key

Каждый уровень имеет собственную ответственность:

Уровень Назначение
Язык Изоляция локали
Namespace Модульность
Ключ Конкретный перевод

Namespace как механизм масштабирования

Namespace — один из важнейших элементов архитектуры.

Без namespaces крупное приложение быстро превращается в огромный файл:

{
  "save": "Save",
  "cancel": "Cancel",
  "profile_edit_button": "Edit profile",
  "dashboard_sidebar_menu": "Menu"
}

I18next предлагает разделение:

locales/
  en/
    common.json
    auth.json
    dashboard.json

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

i18next.init({
  ns: ["common", "auth", "dashboard"],
  defaultNS: "common"
})

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

t("login", { ns: "auth" })

Архитектурные преимущества namespaces

Изоляция доменных областей

Каждый модуль хранит собственные переводы.

Lazy loading

Загрузка только нужных переводов:

i18next.loadNamespaces("dashboard")

Снижение размера initial bundle

Особенно важно для SPA-приложений.

Упрощение командной разработки

Разные команды работают с разными namespaces.

Backend-архитектура

I18next не навязывает способ хранения переводов.

Поддерживаются:

  • JSON-файлы;
  • REST API;
  • CDN;
  • базы данных;
  • CMS;
  • облачные платформы локализации.

Это достигается через backend abstraction layer.

Пример подключения backend:

import Backend from "i18next-http-backend"

i18next
  .use(Backend)
  .init({
    backend: {
      loadPath: "/locales/{{lng}}/{{ns}}.json"
    }
  })

Backend как стратегия загрузки

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

Библиотека не знает:

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

Она лишь вызывает backend API.

Это соответствует принципу Dependency Inversion из SOLID.

Асинхронная архитектура

I18next изначально проектировался как асинхронная система.

Причины:

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

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

await i18next.init({
  lng: "en"
})

Смена языка:

await i18next.changeLanguage("de")

Event-driven модель

Внутри библиотеки активно используется событийная архитектура.

Например:

i18next.on("languageChanged", (lng) => {
  console.log("Новый язык:", lng)
})

Другие события:

Событие Назначение
initialized Завершение инициализации
loaded Загрузка ресурсов
failedLoading Ошибка загрузки
missingKey Отсутствующий перевод

Такой подход делает библиотеку расширяемой и хорошо интегрируемой.

Принцип fallback

Один из центральных принципов I18next — отказоустойчивость локализации.

Если перевод отсутствует:

t("unknown.key")

система пытается:

  1. найти ключ в текущем namespace;
  2. проверить fallback namespace;
  3. проверить fallback language;
  4. вернуть ключ как текст.

Настройка:

i18next.init({
  fallbackLng: "en"
})

Fallback Chain

Механизм fallback образует цепочку разрешения:

fr-CA
  ↓
fr
  ↓
en

Это особенно важно для региональных локалей:

  • en-US
  • en-GB
  • pt-BR
  • zh-Hans

Интерполяция как отдельный слой

I18next отделяет хранение текста от динамических данных.

Пример:

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

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

t("welcome", {
  name: "Алексей"
})

Архитектурно это реализовано через отдельный interpolator module.

Экранирование и безопасность

По умолчанию интерполяция экранирует HTML:

{
  interpolation: {
    escapeValue: true
  }
}

Это защищает от XSS-атак.

Пример опасного значения:

{
  name: "<script>alert(1)</script>"
}

После экранирования вредоносный код не выполнится.

Плюрализация как самостоятельный механизм

Разные языки имеют разные формы множественного числа.

Например:

Язык Форм
Английский 2
Русский 3
Арабский 6

I18next содержит отдельный plural resolver.

Пример:

{
  "item_one": "{{count}} предмет",
  "item_few": "{{count}} предмета",
  "item_many": "{{count}} предметов"
}

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

t("item", { count: 5 })

Соответствие стандарту ICU

Хотя ядро I18next использует собственную модель pluralization, архитектура допускает ICU-формат через плагины.

Это важно для:

  • enterprise-систем;
  • сложных локализаций;
  • интеграции с профессиональными переводческими платформами.

Принцип расширяемости через plugins

I18next построен как plugin-oriented architecture.

Подключение:

i18next
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)

Каждый плагин расширяет pipeline библиотеки.

Основные типы плагинов

Тип Назначение
Backend Загрузка переводов
Detector Определение языка
Formatter Форматирование
Post Processor Постобработка
Framework Adapter Интеграция с UI

Language Detection Architecture

Определение языка реализовано как цепочка стратегий.

Пример:

detection: {
  order: [
    "querystring",
    "cookie",
    "localStorage",
    "navigator"
  ]
}

Каждый detector проверяется последовательно.

Приоритетность источников языка

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

Типичный приоритет:

URL
  ↓
Cookie
  ↓
LocalStorage
  ↓
Browser Language

Кэширование переводов

I18next поддерживает несколько уровней кэширования:

  • in-memory cache;
  • localStorage;
  • sessionStorage;
  • серверный cache layer.

Это особенно важно для:

  • SSR;
  • CDN;
  • мобильных приложений;
  • offline-first архитектур.

Архитектура ключей перевода

Существует два подхода к именованию ключей.

Semantic Keys

{
  "button.save": "Сохранить"
}

Natural Keys

{
  "Save changes": "Сохранить изменения"
}

Философия I18next ближе к semantic keys, поскольку они:

  • стабильнее;
  • не зависят от текста;
  • безопаснее при рефакторинге;
  • проще масштабируются.

Nested Translation Structure

I18next поддерживает вложенные структуры:

{
  "auth": {
    "login": {
      "title": "Вход"
    }
  }
}

Доступ:

t("auth.login.title")

Это позволяет организовывать переводы как полноценную доменную модель.

Separation of Concerns

Архитектура I18next чётко разделяет:

Ответственность Подсистема
Хранение переводов Resource Store
Получение переводов Backend
Выбор языка Detector
Разрешение ключей Translator
Форматирование Formatter
Интерполяция Interpolator

Такое разделение делает систему гибкой и тестируемой.

Runtime Localization

I18next ориентирован на runtime localization.

Язык можно менять без перезагрузки приложения:

i18next.changeLanguage("fr")

Это критически важно для:

  • SPA;
  • desktop-приложений;
  • embedded UI;
  • админ-панелей.

Архитектура реактивности

Во фреймворках вроде React библиотека использует реактивную модель обновления интерфейса.

После изменения языка:

i18next.changeLanguage("de")

компоненты автоматически перерисовываются.

Это достигается через подписку на события I18next.

Принцип минимального ядра

Ядро библиотеки относительно небольшое.

Дополнительные возможности подключаются отдельно:

  • backend;
  • ICU;
  • browser detector;
  • React integration;
  • formatter plugins.

Такой подход уменьшает:

  • размер bundle;
  • связность модулей;
  • количество лишнего кода.

Совместимость с SSR

Архитектура I18next учитывает серверный рендеринг.

Основные задачи SSR:

  • предварительная загрузка переводов;
  • предотвращение hydration mismatch;
  • синхронизация языка между сервером и клиентом.

Поэтому библиотека поддерживает:

  • preload namespaces;
  • server-side resource injection;
  • language hydration.

Изоляция состояния

Каждый экземпляр I18next хранит собственное состояние:

const instance = i18next.createInstance()

Это важно для:

  • SSR;
  • multi-tenant приложений;
  • микрофронтендов;
  • тестирования.

Архитектурная роль createInstance

Глобальный singleton удобен для небольших проектов:

import i18next from "i18next"

Но в enterprise-архитектуре предпочтительнее изолированные экземпляры.

Причины:

  • отсутствие shared state;
  • предсказуемость;
  • независимые конфигурации;
  • безопасный SSR.

Принцип progressive enhancement

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

i18next.init({
  resources,
  lng: "ru"
})

А затем постепенно добавлять:

  • namespaces;
  • lazy loading;
  • SSR;
  • detectors;
  • backend;
  • ICU;
  • кэширование.

Это делает библиотеку пригодной как для небольших проектов, так и для enterprise-систем.

Подход к отсутствующим переводам

I18next рассматривает missing translations как часть рабочего процесса локализации.

Настройки:

saveMissing: true

Событие:

missingKey

Архитектурно это позволяет:

  • автоматически собирать новые ключи;
  • интегрироваться с TMS;
  • отслеживать качество локализации.

Архитектура post-processing

После получения перевода текст может проходить через цепочку post-processors.

Пример:

i18next.use({
  type: "postProcessor",
  name: "uppercase",

  process(value) {
    return value.toUpperCase()
  }
})

Это создаёт pipeline обработки:

translation
  ↓
interpolation
  ↓
pluralization
  ↓
post-processing

Инкапсуляция локализационной логики

I18next стремится скрыть сложность локализации за простым API:

t("welcome")

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

  • поиск namespace;
  • fallback;
  • plural resolution;
  • interpolation;
  • escaping;
  • post-processing;
  • formatter execution.

Такой подход соответствует принципу abstraction over complexity.

Архитектурная философия библиотеки

Основные идеи, лежащие в основе I18next:

Принцип Реализация
Модульность Plugins, namespaces
Масштабируемость Lazy loading, backend abstraction
Независимость Отсутствие привязки к UI
Расширяемость Plugin architecture
Отказоустойчивость Fallback chain
Изоляция ответственности Separate subsystems
Runtime-динамика Смена языка без reload
Enterprise-ready SSR, caching, async loading

Именно сочетание этих принципов делает I18next не просто библиотекой переводов, а полноценной инфраструктурой интернационализации для крупных JavaScript-приложений.

Оглавление