Дефолтный namespace

В системе i18next организация переводов строится вокруг концепции namespaces — логических контейнеров для разделения ресурсов локализации. Один из них всегда играет особую роль: дефолтный namespace, который используется при отсутствии явного указания.

Namespace в i18next представляет собой независимый набор ключей переводов. Он позволяет:

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

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

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

Здесь common, auth, dashboard — отдельные namespaces.

Понятие дефолтного namespace

Дефолтный namespace — это namespace, который используется системой перевода, если:

  • namespace не указан явно при вызове t();
  • настройка defaultNS задана в конфигурации;
  • ключи запрашиваются без указания области.

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

Конфигурация defaultNS

В i18next настройка задаётся при инициализации:

i18next.init({
  lng: 'en',
  ns: ['common', 'auth', 'dashboard'],
  defaultNS: 'common',
  resources: {
    en: {
      common: {
        welcome: "Welcome"
      },
      auth: {
        login: "Login"
      }
    }
  }
});

Поведение параметра defaultNS

  • 'common' становится базовым пространством имён;
  • вызов t('welcome') ищет ключ в common;
  • если ключ отсутствует — происходит fallback в другие namespaces (в зависимости от конфигурации).

Механика поиска переводов

При вызове функции:

t('welcome');

внутренний алгоритм:

  1. Проверяется defaultNS
  2. Ищется ключ welcome в common
  3. Если не найден — проверяются дополнительные namespaces (если настроены)
  4. Применяется fallback language (если включён)

Явное указание namespace и отличие от defaultNS

Вызов с namespace:

t('auth:login');

или:

t('login', { ns: 'auth' });

В этом случае:

  • defaultNS игнорируется;
  • поиск происходит строго в auth.

Сценарии использования default namespace

Общие тексты интерфейса

Чаще всего дефолтным namespace становится common:

  • кнопки интерфейса;
  • системные сообщения;
  • базовые элементы UI.

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

{
  "welcome": "Welcome",
  "cancel": "Cancel",
  "confirm": "Confirm"
}

Упрощение вызова t()

При правильно настроенном defaultNS можно избегать избыточных указаний:

t('cancel');
t('confirm');

Без необходимости писать:

t('cancel', { ns: 'common' });

Влияние defaultNS на загрузку ресурсов

При использовании backend-подгрузки ресурсов (например, HTTP backend), дефолтный namespace влияет на:

  • первичную загрузку переводов;
  • приоритет загрузки;
  • кеширование.

Если defaultNS = 'common', система сначала запрашивает:

/locales/en/common.json

Комбинация defaultNS и multiple namespaces

При множественных namespaces:

ns: ['common', 'auth', 'dashboard'],
defaultNS: 'common'

поведение становится приоритетным:

  • common используется для всех неуточнённых ключей;
  • остальные namespaces доступны только при явном вызове.

Fallback внутри default namespace

Если включён fallback:

i18next.init({
  fallbackLng: 'en',
  ns: ['common', 'auth'],
  defaultNS: 'common'
});

то порядок поиска может выглядеть так:

  1. common (текущий язык)
  2. auth (если указан в ns)
  3. common (fallback язык)
  4. auth (fallback язык)

Типичные ошибки при работе с defaultNS

1. Потеря переводов из-за неправильного namespace

Если ключ находится в auth, но defaultNS = 'common':

t('login');

результат будет missingKey.

2. Перегрузка common namespace

Частая проблема — помещение всех переводов в defaultNS, что приводит к:

  • росту размера файла;
  • потере модульности;
  • усложнению поддержки.

3. Несогласованность структуры

Если часть команды использует:

t('login')

а часть:

t('auth:login')

возникает дублирование логики и нестабильность архитектуры переводов.

Работа с defaultNS в React интеграции

В связке с React используется hook:

const { t } = useTranslation();

Если не указано:

useTranslation('auth');

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

Пример:

const { t } = useTranslation();

return <button>{t('cancel')}</button>;

Ключ ищется в default namespace.

Динамическое изменение default namespace

В i18next можно изменить namespace на лету:

i18next.setDefaultNamespace('dashboard');

После этого:

t('title');

будет искать ключ в dashboard.

Связь defaultNS и архитектуры приложения

Выбор дефолтного namespace влияет на структуру проекта:

UI-ориентированная архитектура

  • defaultNS = common
  • остальные namespaces = модули

Модульная архитектура

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

Поведение при отсутствии defaultNS

Если defaultNS не задан:

  • используется первый namespace из массива ns;
  • поведение становится менее предсказуемым;
  • возрастает зависимость от порядка массивов.

Пример:

ns: ['auth', 'common']

дефолтным станет auth.

Производственные рекомендации по структуре

  • common используется только для действительно общих строк;
  • бизнес-логика разделяется по namespaces;
  • defaultNS не перегружается доменной логикой;
  • ключи остаются короткими и семантически чистыми.

Итоговое поведение системы поиска ключей

Алгоритм разрешения ключа в i18next с учётом default namespace:

  1. Проверка namespace из вызова
  2. Если отсутствует — использование defaultNS
  3. Поиск ключа в выбранном namespace
  4. Проверка fallback namespaces
  5. Проверка fallback language
  6. Возврат ключа-заглушки при отсутствии совпадений
Оглавление