Концепция namespace

В i18next все переводы организуются вокруг централизованного объекта ресурсов, где строки сгруппированы по языкам и логическим областям приложения. Пространство имён (namespace) является механизмом, позволяющим разделять переводы на независимые модули, снижая связанность и упрощая масштабирование локализации.

Базовая структура ресурсов обычно выглядит следующим образом:

{
  en: {
    common: {
      welcome: "Welcome",
      logout: "Logout"
    },
    auth: {
      login: "Login",
      register: "Register"
    }
  },
  ru: {
    common: {
      welcome: "Добро пожаловать",
      logout: "Выйти"
    },
    auth: {
      login: "Вход",
      register: "Регистрация"
    }
  }
}

В этом примере common и auth выступают как независимые пространства имён. Каждое пространство представляет собой отдельный словарь переводов внутри одного языка.

Сущность namespace в архитектуре i18next

Пространство имён в i18next — это логический контейнер переводов, связанный с конкретной областью приложения. Оно выполняет роль слоя сегментации, который позволяет:

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

Каждый namespace представляет собой самостоятельный JSON-объект, загружаемый либо заранее, либо динамически через backend-плагин.

Базовая конфигурация namespaces

При инициализации i18next пространства имён задаются через конфигурацию:

import i18n from "i18next";

i18n.init({
  lng: "ru",
  fallbackLng: "en",
  ns: ["common", "auth"],
  defaultNS: "common",
  resources: {
    ru: {
      common: {
        welcome: "Добро пожаловать"
      },
      auth: {
        login: "Вход"
      }
    },
    en: {
      common: {
        welcome: "Welcome"
      },
      auth: {
        login: "Login"
      }
    }
  }
});

Параметр ns определяет список доступных пространств имён, а defaultNS задаёт пространство, используемое по умолчанию при отсутствии явного указания.

Обращение к переводам внутри namespace

Формат ключей включает указание пространства имён через разделитель ::

i18n.t("common:welcome");
i18n.t("auth:login");

Если defaultNS установлен, обращение может быть сокращено:

i18n.t("welcome"); // берётся из common

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

Логическая декомпозиция переводов

Разделение на namespaces чаще всего отражает архитектуру приложения. Типичные подходы:

  • common — базовые строки интерфейса (кнопки, общие сообщения)
  • auth — авторизация и регистрация
  • dashboard — элементы панели управления
  • errors — сообщения об ошибках
  • validation — тексты валидации форм

Пример распределения:

{
  en: {
    errors: {
      notFound: "Not found",
      unauthorized: "Unauthorized access"
    },
    validation: {
      required: "This field is required",
      email: "Invalid email format"
    }
  }
}

Такое разделение позволяет поддерживать независимость модулей интерфейса от текстового слоя.

Динамическая загрузка namespaces

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

i18n.loadNamespaces("dashboard").then(() => {
  console.log(i18n.t("dashboard:title"));
});

В связке с backend-плагинами загрузка может происходить автоматически при обращении к namespace.

Использование backend для загрузки namespace

При использовании HTTP backend ресурсы часто хранятся в отдельных файлах:

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

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

import Backend from "i18next-http-backend";

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

Здесь параметр {{ns}} автоматически подставляет имя пространства имён, что делает структуру файлов предсказуемой и масштабируемой.

Переключение namespace во время выполнения

i18next поддерживает изменение активных пространств имён:

i18n.setDefaultNamespace("auth");

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

fallback и приоритет namespace

При поиске перевода система проходит по цепочке:

  1. текущий язык + указанный namespace
  2. fallback язык + тот же namespace
  3. fallback namespace (если задан)

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

i18n.init({
  fallbackLng: "en",
  fallbackNS: "common"
});

Это обеспечивает устойчивость интерфейса при отсутствии отдельных переводов.

Использование нескольких namespaces одновременно

В некоторых случаях требуется загрузка нескольких пространств имён сразу:

i18n.init({
  ns: ["common", "auth", "dashboard", "errors"],
  defaultNS: "common",
  load: "currentOnly"
});

Параметр load определяет стратегию загрузки языков и namespaces. Значение currentOnly ограничивает загрузку только активными контекстами.

Интеграция namespace с React-подходом

В связке с react-i18next namespaces используются для изоляции переводов компонентов:

import { useTranslation } from "react-i18next";

function LoginForm() {
  const { t } = useTranslation("auth");

  return (
    <button>{t("login")}</button>
  );
}

Здесь пространство имён фиксируется на уровне компонента, что снижает риск конфликтов ключей.

Namespace и коллизии ключей

При отсутствии пространств имён возникает риск дублирования ключей:

{
  login: "..."
}

Один и тот же ключ может использоваться в разных контекстах с разными значениями. Namespace устраняет эту проблему:

auth: {
  login: "Sign in"
},
dashboard: {
  login: "Enter panel"
}

Обращение становится однозначным:

i18n.t("auth:login");
i18n.t("dashboard:login");

Производительность и оптимизация через namespaces

Разделение переводов влияет на производительность за счёт:

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

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

Namespace как часть масштабируемой i18n-модели

В крупных системах namespaces становятся фундаментом организации переводов. Они связываются с:

  • микрофронтендами;
  • feature-based архитектурой;
  • модульными бандлерами;
  • ленивой загрузкой маршрутов.

Каждый модуль может иметь собственный namespace, автономно развиваться и подключаться к общему i18next-инстансу без пересечения ключей и конфликтов ресурсов.

Оглавление