Форматы хранения: JSON, JSON5, YAML

Формат JSON является основным способом хранения переводов в i18next и используется по умолчанию в большинстве конфигураций. Его ключевая особенность — строгая структура и предсказуемость, что делает его удобным для автоматической обработки и интеграции в сборочные процессы.

Структура обычно строится вокруг ключей, где каждый ключ соответствует строке интерфейса или группе строк:

{
  "welcome": "Добро пожаловать",
  "button": {
    "save": "Сохранить",
    "cancel": "Отмена"
  }
}

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

  • button.save
  • button.cancel

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

Особое значение в JSON-структурах имеют интерполяции:

{
  "greeting": "Привет, {{name}}"
}

i18next заменяет {{name}} значением, переданным в runtime, что позволяет динамически формировать текст без изменения исходного файла переводов.

Поддержка множественных форм реализуется через специальные ключи:

{
  "car_one": "{{count}} машина",
  "car_few": "{{count}} машины",
  "car_many": "{{count}} машин"
}

Система pluralization в i18next выбирает нужную форму на основе правил языка, что критично для языков с развитой морфологией.

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

JSON5

JSON5 расширяет стандарт JSON, добавляя более гибкий синтаксис, который облегчает поддержку файлов переводов в крупных проектах.

Основные отличия от JSON:

  • допустимы комментарии
  • допускаются одинарные кавычки
  • разрешены trailing commas
  • ключи можно не заключать в кавычки при простых именах

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

{
  // Главное приветствие
  welcome: 'Добро пожаловать',

  button: {
    save: 'Сохранить',
    cancel: 'Отмена', // кнопка отмены
  },
}

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

Интерполяции и pluralization работают идентично JSON, поскольку различие касается только синтаксиса хранения, а не логики i18next.

{
  greeting: 'Привет, {{name}}',
  message_one: '{{count}} сообщение',
  message_other: '{{count}} сообщений',
}

JSON5 часто используется в локальных средах разработки, где важно удобство редактирования и читаемость. Однако в production-сборках такие файлы нередко транспилируются в строгий JSON для повышения совместимости.

YAML

YAML применяется как альтернатива JSON в проектах, где приоритетом является читаемость и компактность записи. Он особенно удобен для больших файлов переводов, содержащих глубокую вложенность.

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

welcome: "Добро пожаловать"

button:
  save: "Сохранить"
  cancel: "Отмена"

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

Интерполяция в YAML полностью совместима с механизмом i18next:

greeting: "Привет, {{name}}"

Pluralization также реализуется через суффиксы ключей:

car_one: "{{count}} машина"
car_few: "{{count}} машины"
car_many: "{{count}} машин"

YAML поддерживает комментарии, что используется для документирования переводов:

# Текст отображается на главной странице
welcome: "Добро пожаловать"

В сравнении с JSON и JSON5 YAML обладает более высокой читаемостью, но требует аккуратного обращения с отступами и не допускает произвольных структурных ошибок.

Сравнение структурных особенностей

JSON, JSON5 и YAML решают одну задачу — хранение ключ-значение пар переводов, но различаются уровнем строгости и удобством сопровождения.

JSON:

  • строгий синтаксис
  • высокая совместимость
  • отсутствие комментариев
  • удобен для production-сборок

JSON5:

  • расширенный синтаксис
  • поддержка комментариев
  • удобство разработки
  • промежуточный вариант между JSON и YAML

YAML:

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

Вложенные структуры и неймспейсы

i18next активно использует вложенные структуры независимо от выбранного формата. Это позволяет формировать логические модули переводов:

{
  "auth": {
    "login": {
      "title": "Вход",
      "submit": "Войти"
    }
  }
}

или в YAML:

auth:
  login:
    title: "Вход"
    submit: "Войти"

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

Интерполяция и экранирование

Во всех трёх форматах используется единый механизм плейсхолдеров i18next:

  • {{variable}} — базовая подстановка
  • {{variable, format}} — форматирование значений

Пример:

{
  "price": "Цена: {{value}} ₽"
}

Особое внимание уделяется экранированию символов, особенно в YAML, где кавычки и двоеточия могут влиять на структуру документа.

Плюрализация и языковые правила

i18next использует CLDR-правила для определения форм множественного числа. Структура ключей зависит от языка и может включать несколько форм:

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

В YAML и JSON5 структура сохраняется идентичной, так как логика pluralization обрабатывается библиотекой, а не форматом хранения.

Особенности загрузки ресурсов

Форматы JSON, JSON5 и YAML интегрируются в i18next через загрузчики ресурсов. На уровне конфигурации происходит преобразование файлов в объектную структуру:

  • JSON загружается нативно через fetch или require
  • JSON5 требует парсинга через специализированные парсеры
  • YAML требует предварительного преобразования в JSON-объект

Это влияет на сборку приложения, поскольку YAML и JSON5 обычно требуют дополнительных шагов трансформации на этапе bundling.

Производительность и сборка

JSON обладает наименьшими накладными расходами при загрузке, так как парсится встроенными средствами JavaScript. JSON5 и YAML требуют дополнительных библиотек, что увеличивает размер бандла и время инициализации.

В крупных приложениях часто применяется стратегия:

  • разработка ведётся в JSON5 или YAML
  • сборка преобразует данные в JSON
  • runtime использует только JSON

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

Оглавление