Как переводить файлы i18next JSON в React и Next.js (2026)

Вы только что закончили приложение React, которое должно быть выпущено на 12 языках к следующей пятнице. Ваши файлы локализации находятся в public/locales/en/common.json, у вас 340 ключей на каждую локаль, а токены внутри ваших строк выглядят как {{userName}} и {{count}}, разбросанные по вложенным объектам. Вы вставляете JSON в ChatGPT, и он возвращает {{ nombreUsuario }}, лишние пробелы и половину переименованных ключей множественного числа. Ваше приложение падает при сборке.

Если вы пытались автоматизировать перевод i18next JSON, вы знаете эту боль. Формат JSON гибок, и именно поэтому большинство инструментов перевода искажают его. Настоящая проблема не в качестве языковой модели — а в том, что потребительские AI-инструменты не понимают структурные правила i18next.

Это руководство объясняет, чем i18next JSON отличается от других форматов локализации, почему наивные подходы к переводу ломают приложения React и Next.js, и как безопасно автоматизировать перевод десятков локалей без ручной проверки каждого ключа.

Что такое i18next JSON и почему его перевод сложен

i18next — наиболее широко используемая библиотека i18n в экосистеме JavaScript. Она используется в React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue и серверных службах Node. Она хранит переводимые строки в плоских или вложенных файлах JSON, по одному на каждую локаль.

Типичный файл выглядит так:

{
  "welcome": "Welcome, {{userName}}!",
  "cart": {
    "empty": "Your cart is empty",
    "items_one": "{{count}} item in your cart",
    "items_other": "{{count}} items in your cart"
  },
  "errors": {
    "network": "Network error. <strong>Please retry</strong>."
  }
}

Это выглядит просто, но три вещи делают его опасным для перевода с помощью универсального AI.

Токены интерполяции являются структурными, а не текстовыми

Последовательность {{userName}} — это не слово, это заполнитель, который среда выполнения заменяет данными. Добавьте пробел ({{ userName }}), переименуйте его или переведите внутренний идентификатор, и среда выполнения либо тихо завершится с ошибкой, либо выдаст исключение. Некоторые переводчики услужливо преобразуют {{count}} в {{conteo}} на испанском. Ваше приложение теперь пытается интерполировать переменную, которая не существует, и отображает необработанный заполнитель вашему пользователю.

Ключи множественного числа — это магические суффиксы

i18next определяет множественное число по суффиксам: _zero, _one, _two, _few, _many, _other. Это не произвольные строки — они должны соответствовать категориям множественного числа CLDR для целевой локали. Английский использует только _one и _other. Русский, арабский и польский используют до шести категорий. Если ваш переводчик отбросит _other или переименует его, цепочка резервных вариантов нарушится.

Вложенные ключи должны оставаться неизменными

В отличие от файлов Gettext .po, которые представляют собой плоские пары ключ-значение, файлы i18next могут быть произвольно вложенными. Ленивый переводчик может выровнять структуру, изменить имена ключей, чтобы они соответствовали переведенному тексту, или переупорядочить объекты. Ваш вызов t('cart.items_other') в коде больше не будет разрешаться.

Плохие решения, которые разработчики пробуют первыми

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

Этап первый: Вставка в ChatGPT

Вы копируете 200 ключей в ChatGPT, просите "перевести этот JSON на испанский" и вставляете результат обратно. Это работает для 180 ключей. Двадцать имеют добавленные пробелы внутри {{...}}, три имеют переписанные суффиксы множественного числа, а один тег <strong> был переведен как <fuerte>. Ваша сборка либо завершается с ошибкой, либо поставляет в продакшн незаметно сломанные строки.

Этап второй: Google Translate API

Вы подключаете Google Translate REST API, итерируете по вашему JSON и отправляете каждое значение. Скорость отличная. Качество — нет. API Google обрабатывает каждую строку изолированно — нет контекста о вашем приложении, нет понимания того, что {{count}} является заполнителем, нет осознания того, что ключ cart.empty отличается от cart.items_one. Вам все еще требуется ручная проверка каждого ключа.

Этап третий: Коммерческие платформы TMS

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

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

Безопасный подход: Синтаксически-ориентированный перевод

Единственный надежный способ масштабно переводить i18next JSON — это использовать инструмент, который сначала анализирует формат, фиксирует синтаксис и отправляет для перевода AI только переводимый текст.

Вот что делает синтаксически-ориентированная обработка под капотом:

1. Парсит JSON в абстрактное дерево, сохраняя пути ключей и вложенность.
2. Идентифицирует токены интерполяции ({{name}}, {{count, number}}, {{date, datetime}}) и заменяет их идентификаторами заполнителей.
3. Идентифицирует HTML-теги внутри компонентов Trans (<0>, <strong>, <br/>) и фиксирует их.
4. Обнаруживает ключи множественного числа по суффиксу и сопоставляет их с правилами CLDR для целевой локали.
5. Отправляет только очищенный текст в LLM с контекстом о пути ключа.
6. Вставляет исходные токены и теги обратно в их точные позиции.
7. Проверяет вывод — если какой-либо заполнитель отсутствует или неправильно сформирован, возвращается к источнику.

Это тот же принцип, который обеспечивает безопасность облачного перевода PO. Если вам интересна базовая архитектура, наше сравнение качества AI-перевода подробно описывает, как различные LLM справляются с этими ограничениями.

Пошаговое руководство: Перевод i18next JSON с помощью SimplePoTranslate

SimplePoTranslate поддерживает i18next JSON нативно в планах Pro и Lifetime. Бесплатный уровень в настоящее время охватывает .po и .pot — обновитесь или используйте пробную версию для доступа к JSON.

1. Подготовьте исходный файл

Используйте ваш английский (или исходный языковой файл) в качестве основного. Убедитесь, что это валидный JSON и он содержит все ключи, используемые вашим приложением. Распространенная ошибка — оставлять устаревшие или неиспользуемые ключи, что расходует вашу квоту на перевод для строк, которые вы никогда не будете отображать.

# From your project root
cp public/locales/en/common.json ~/Desktop/common.json

2. Загрузите в SimplePoTranslate

Войдите в свою панель управления, нажмите New Translation и загрузите common.json. Платформа автоматически определяет формат i18next. Выберите целевой язык из 41 поддерживаемой локали, выберите тон (профессиональный, непринужденный, маркетинговый) и отправьте.

3. Дайте движку поработать

Под капотом файл парсится, разбивается на безопасные пакеты и переводится параллельно. Токены интерполяции заблокированы. Суффиксы множественного числа сохраняются и сопоставляются с правилами CLDR целевой локали. HTML внутри компонентов Trans остается нетронутым.

4. Скачайте ZIP-архив

Вы получаете ZIP-архив, содержащий переведенный JSON плюс альтернативные форматы (.php для приложений PHP, .po для совместимости с различными инструментами). Поместите JSON в public/locales/es/common.json и повторно разверните.

unzip common_es.zip
mv common.json public/locales/es/common.json
npm run build

5. Повторяйте или пакетно обрабатывайте

Для всех 12 целевых локалей отправьте 12 заданий. Квоты плана Pro покрывают десятки типичных SaaS-приложений. Для монорепозиториев с несколькими файлами пространств имен загружайте каждый отдельно или обрабатывайте их пакетно.

Интеграция переводов обратно в ваше приложение

Как только вы перевели файлы JSON, интеграция становится простой частью. Несколько подводных камней:

• Проверьте категории множественного числа. Выполните быстрый смоук-тест для каждой локали: отрендерите компонент с count={0}, count={1}, count={5} и убедитесь, что все три значения выдают правильную строку.
• Проверьте локали с письмом справа налево (RTL). Если вы переводили на арабский, иврит или фарси, ваш UI нуждается в CSS, поддерживающем RTL. Наше руководство по RTL-переводу WordPress охватывает шаблоны CSS, применимые и к приложениям React.
• Настройте цепочку резервных вариантов. Настройте i18next на откат к английскому, если ключ отсутствует, чтобы состояния в процессе развертывания не приводили к сбоям у пользователей.
• Заблокируйте ваш исходный файл в CI. Добавьте проверку, которая отклоняет PR, где en/common.json изменяется без перегенерации других локалей. Отклонение перевода — это самая большая причина ошибок i18n в продакшене.

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

Когда JSON недостаточно: Обработка сложных случаев

Некоторые граничные случаи требуют особого внимания.

ICU MessageFormat

Если ваш проект использует синтаксис ICU ({count, plural, one {1 item} other {# items}}), i18next рассматривает его как интерполяцию, но структура более сложна. Убедитесь, что ваш инструмент перевода распознает параметры ICU и не переводит названия категорий, такие как one, other, или идентификаторы формата, такие как plural, number, date.

Компонент Trans с React-узлами

<Trans> отображает компоненты React внутри переведенных строк, с ключами по индексу (<0>, <1>). Переводчик должен сохранять точный порядок тегов. Синтаксический замок SimplePoTranslate справляется с этим, но если вы используете другой инструмент, проверьте перед выпуском.

Файлы пространств имен

Большие приложения делят локали на пространства имен: common.json, dashboard.json, checkout.json. Переводите каждый файл независимо — не объединяйте их. Качество контекста выше, когда пути ключей каждого пространства имен остаются ограниченными.

Подводя итог

Перевод i18next JSON для приложения React или Next.js — это не выбор лучшей модели AI. Это соблюдение структурных правил формата: интерполяции, суффиксы множественного числа, вложенные ключи и HTML-теги должны пройти полный цикл без изменений. Потребительские AI-инструменты рассматривают JSON как неструктурированный текст. Синтаксически-ориентированные инструменты парсят его как структурированные данные и касаются только переводимых поверхностей.

Если вы выпускаете многоязычное приложение и копировали JSON в чат-интерфейсы, вы уже знаете цену: часы ручной проверки для каждой локали, случайные производственные ошибки и растущий ворох сломанных форм множественного числа. Конвейер, учитывающий формат, устраняет каждый из этих режимов отказа.

Готовы безопасно переводить ваши файлы i18next JSON? Попробуйте SimplePoTranslate бесплатно — кредитная карта не требуется. Загрузите один раз, опубликуйте на 41 языке.