Синтаксис plural форм

Механизм plural-форм в i18next не является отдельной абстракцией — он встроен в систему ключей переводов и активируется через передачу числового параметра count. Именно count определяет, какая форма перевода будет выбрана: единственное, множественное или одна из языковых вариаций (zero, one, few, many, other).

i18next.t('cart.items', { count: 1 });
i18next.t('cart.items', { count: 5 });

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

Базовая структура plural-ключей

Самая распространённая схема — суффиксы _one и _other. Она используется в языках с простой системой множественного числа (например, английский, русский в базовой конфигурации через CLDR-правила).

{
  "cart": {
    "items_one": "{{count}} товар",
    "items_other": "{{count}} товаров"
  }
}
i18next.t('cart.items', { count: 1 }); // 1 товар
i18next.t('cart.items', { count: 5 }); // 5 товаров

Ключевой принцип: базовый ключ (items) служит префиксом, а библиотека автоматически добавляет суффикс в зависимости от языка и правила pluralization.

Полный набор форм множественного числа

В языках с богатой морфологией используется расширенный набор форм:

  • zero
  • one
  • two
  • few
  • many
  • other

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

{
  "apples_zero": "нет яблок",
  "apples_one": "{{count}} яблоко",
  "apples_few": "{{count}} яблока",
  "apples_many": "{{count}} яблок",
  "apples_other": "{{count}} яблока"
}

Выбор формы зависит от языковых правил CLDR, встроенных в i18next через pluralResolver.

Роль параметра count в выборе формы

count не просто подставляется в строку — он участвует в вычислении ключа перевода.

i18next.t('apples', { count: 21 });

Логика работы:

  1. берётся ключ apples
  2. определяется язык (lng)
  3. применяется plural-правило языка
  4. формируется ключ вида apples_few, apples_many и т.д.
  5. выполняется подстановка {{count}}

Интерполяция значения count

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

{
  "messages_one": "{{count}} сообщение",
  "messages_other": "{{count}} сообщений"
}
i18next.t('messages', { count: 3 });

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

{
  "files_one": "Файл {{name}} ({{count}} элемент)",
  "files_other": "Файлы {{name}} ({{count}} элементов)"
}

Особенности ключа без явного _one

Если определён только базовый ключ и _other, библиотека использует его как fallback:

{
  "comments_other": "{{count}} комментариев"
}
i18next.t('comments', { count: 10 });

При count = 1 возможен fallback на other, если one отсутствует, что приводит к грамматически неточной форме. Это поведение критично учитывать при проектировании словарей.

Языковые правила и CLDR-модель

i18next опирается на CLDR plural rules, где каждый язык имеет собственную функцию выбора формы.

Пример различий:

  • английский: one / other
  • русский: one / few / many / other
  • японский: всегда other
  • арабский: шесть форм

Эта логика инкапсулирована, но влияет на структуру ключей.

Контекст plural и контекстные суффиксы

В i18next контекст (context) и plural могут комбинироваться, создавая составные ключи:

{
  "car_male_one": "Он купил {{count}} машину",
  "car_female_one": "Она купила {{count}} машину",
  "car_male_other": "Он купил {{count}} машин",
  "car_female_other": "Она купила {{count}} машин"
}
i18next.t('car', {
  count: 2,
  context: 'female'
});

Порядок обработки:

  1. context (female)
  2. plural form (other)
  3. итоговый ключ car_female_other

Interval plural формы

Отдельный механизм — интервал-переводы, когда форма зависит не от точного числа, а от диапазона.

{
  "items_interval_1": "1 элемент",
  "items_interval_2-4": "{{count}} элемента",
  "items_interval_5-10": "{{count}} элементов"
}

Используется редко, но полезен для UI-метрик и статистик.

Переопределение pluralRules

Возможна настройка кастомной логики через pluralResolver:

i18next.init({
  pluralResolver: {
    addRule: (lng, fn) => {
      // кастомное правило
    }
  }
});

Это применяется при нестандартных языках или бизнес-логике, где CLDR недостаточен.

Особенности fallback и отсутствующих форм

Если отсутствует нужная форма:

  1. ищется other
  2. затем fallback language (fallbackLng)
  3. затем ключ без суффикса

Пример:

{
  "book_other": "{{count}} книг"
}

При count = 1 будет использована форма other, если one не определён.

Вложенные plural-структуры

Plural-ключи могут находиться внутри вложенных объектов:

{
  "profile": {
    "notifications_one": "1 уведомление",
    "notifications_other": "{{count}} уведомлений"
  }
}
i18next.t('profile.notifications', { count: 7 });

Влияние интерполяции на plural-выбор

Порядок выполнения критичен:

  1. выбор plural формы
  2. интерполяция значений

Это означает, что:

{
  "test_one": "{{count}} item",
  "test_other": "{{count}} items"
}

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

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

Часто встречаются структурные проблемы словарей:

  • отсутствие one формы при языках, где она обязательна
  • использование count без передачи параметра в t
  • смешивание plural и context без системности
  • попытка вручную выбирать форму вместо использования count

Пример ошибочного подхода:

i18next.t(count > 1 ? 'items_plural' : 'items_single');

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

Совмещение plural с форматтерами

Plural-значение может комбинироваться с форматированием:

{
  "price_one": "{{count}} товар за {{price, currency}}",
  "price_other": "{{count}} товаров за {{price, currency}}"
}
i18next.t('price', {
  count: 3,
  price: 1200
});

Форматтеры выполняются после выбора формы.

Поведение при нулевом значении

count = 0 обрабатывается согласно языковым правилам:

  • в английском → other
  • в русском → часто many или other, зависит от конфигурации
  • может быть отдельная форма zero
{
  "messages_zero": "нет сообщений",
  "messages_one": "{{count}} сообщение",
  "messages_other": "{{count}} сообщений"
}

Приоритет выбора ключей

Алгоритм выбора:

  1. key_context_plural
  2. key_plural
  3. key_context
  4. key_other
  5. key

Этот порядок обеспечивает максимальную специфичность перевода при сохранении fallback-устойчивости.

Оглавление