Документирование контекста для переводчиков

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

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

{
  "user": "Пользователь",
  "user_male": "Пользователь (мужчина)",
  "user_female": "Пользователь (женщина)"
}

При вызове:

i18next.t('user', { context: 'male' });

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

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

Документирование допустимых контекстов

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

{
  "user_male": "Пользователь (мужчина)",
  "user_female": "Пользователь (женщина)",
  "_meta": {
    "user": {
      "context": ["male", "female"],
      "description": "Заголовок профиля пользователя в зависимости от пола"
    }
  }
}

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

Использование описаний ключей

Во многих рабочих процессах i18next интегрируется с системами перевода (Locize, Crowdin, Phrase), где поддерживаются описания ключей. Эти описания отображаются переводчикам и позволяют избежать неоднозначности.

Пример структуры с описанием:

{
  "save_button": {
    "translation": "Сохранить",
    "description": "Кнопка сохранения формы редактирования профиля"
  }
}

В классическом JSON-бандле i18next такое поле не обрабатывается напрямую, но при использовании препроцессоров (например, i18next-scanner или i18next-parser) описания извлекаются и передаются в систему переводов.

Контекст через options и runtime-резолвинг

Помимо суффиксов, контекст может задаваться динамически:

i18next.t('notification', { context: 'error' });

Ресурсы:

{
  "notification_error": "Произошла ошибка",
  "notification_success": "Операция выполнена успешно"
}

Такой механизм особенно полезен для UI-состояний: success, error, warning, info, empty.

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

Контекст и грамматические формы

В языках с развитой морфологией контекст часто пересекается с плурализацией. i18next поддерживает стандартные формы:

{
  "item_one": "элемент",
  "item_few": "элемента",
  "item_many": "элементов"
}

При этом контекст может накладываться поверх числа:

{
  "cart_male_one": "товар (добавлен мужчиной) - {{count}} штука",
  "cart_male_other": "товар (добавлен мужчиной) - {{count}} штук"
}

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

Описание контекста в генераторах ресурсов

Инструменты анализа кода позволяют автоматически извлекать ключи и добавлять к ним комментарии. Например, i18next-scanner поддерживает комментарии в исходном коде:

// t('profile.status', { context: 'active' }) - статус активного профиля

После обработки формируется структура:

{
  "profile": {
    "status_active": "Активный профиль"
  }
}

Дополнительно может формироваться файл описаний:

{
  "profile.status_active": {
    "description": "Статус профиля пользователя в активном состоянии"
  }
}

Такая модель повышает прозрачность переводов и снижает зависимость от контекста кода.

Контекст через namespace и структурирование доменов

Контекст может быть выражен не только через ключи, но и через namespaces:

i18next.t('auth:status', { context: 'expired' });

Ресурсы:

{
  "auth": {
    "status_expired": "Сессия истекла",
    "status_active": "Активная сессия"
  }
}

В этом случае документирование должно фиксировать:

  • назначение namespace;
  • список возможных контекстов внутри домена;
  • зависимость от бизнес-сценариев.

Явное описание контекста в дизайн-системах

При интеграции i18next в дизайн-системы контекст становится частью UI-спецификации. Для каждого компонента фиксируются состояния, которые напрямую отображаются в переводах:

  • button.state: default, loading, disabled
  • alert.type: success, error, warning
  • user.role: admin, editor, guest

Пример связанного ресурса:

{
  "button_submit_default": "Отправить",
  "button_submit_loading": "Отправка..."
}

Документирование таких связок позволяет избежать расхождения между компонентами и локализацией.

Контекст и ICU-расширения

При использовании i18next-icu контекст частично заменяется ICU-выражениями, где логика переносится в саму строку:

{
  "inbox": "{count, plural, one {сообщение} few {сообщения} many {сообщений} other {сообщений}}"
}

Однако даже в этом случае контекст (например, тип сообщения) может добавляться отдельно:

{
  "inbox_error": "Не удалось загрузить сообщения",
  "inbox_empty": "Нет сообщений"
}

Документирование разделяет логику числа и бизнес-состояния как независимые измерения.

Стандартизация контекстных ключей

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

  • суффиксы контекста отделяются через _ или contextSeparator
  • фиксированный набор контекстов
  • запрет на произвольные значения без регистрации
  • обязательные описания для каждого контекстного ключа

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

i18next.init({
  keySeparator: '.',
  contextSeparator: '_'
});

Такая настройка делает структуру предсказуемой и облегчает генерацию документации.

Связь контекста и качества перевода

Отсутствие документированного контекста приводит к типичным проблемам:

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

Документирование решает эти проблемы через явное описание:

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

Контекст в больших ресурсных файлах

В крупных проектах JSON-структуры становятся многоуровневыми:

{
  "profile": {
    "edit": {
      "title": "Редактирование профиля",
      "title_readonly": "Просмотр профиля"
    }
  }
}

Здесь контекст выражен через вложенность, а не через суффиксы. Документирование должно фиксировать семантику уровней, чтобы избежать дублирования ключей на одном уровне абстракции.

Автоматическая генерация контекстной документации

Сборка ресурсов часто включает этап генерации документации:

  • извлечение ключей из исходного кода;
  • анализ параметров t() вызовов;
  • сбор комментариев разработчиков;
  • объединение с метаданными переводческой платформы.

Результатом становится единый реестр:

{
  "key": "notification_error",
  "context": ["error"],
  "description": "Сообщение об ошибке операции"
}

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

Оглавление