Як перекласти JSON-файли i18next у React та Next.js (2026)

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

Якщо ви намагалися автоматизувати переклад i18next JSON, ви знаєте цей біль. Формат JSON є гнучким, і саме тому більшість інструментів перекладу його спотворюють. Справжня проблема не в якості мовної моделі – а в тому, що споживчі інструменти ШІ не розуміють структурних правил i18next.

Цей посібник розповідає, чим JSON i18next відрізняється від інших форматів локалі зації, чому наївні підходи до перекладу ламають застосунки 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>."
  }
}

Це здається простим, але три речі роблять переклад за допомогою універсального ШІ небезпечним.

Токени інтерполяції є структурними, а не текстом

Послідовність {{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>. Ваша збірка або завершується з помилкою, або відправляє мовчки пошкоджені рядки в продакшн.

Етап другий: API Google Translate

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

Етап третій: Комерційні TMS-платформи

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

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

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

Єдиний надійний спосіб масштабно перекладати i18next JSON — це використовувати інструмент, який спочатку аналізує формат, блокує синтаксис і надсилає на ШІ лише текст, що підлягає перекладу.

Ось що робить синтаксично-орієнтована обробка:

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

Це той самий принцип, який робить безпечним хмарний переклад PO. Якщо вам цікава базова архітектура, наш порівняльний аналіз якості перекладу ШІ детально розбирає, як різні 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

Увійдіть до своєї панелі керування, натисніть Новий переклад та завантажте 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-локалі. Якщо ви перекладали на арабську, іврит або фарсі, ваш інтерфейс потребує CSS, що підтримує RTL. Наш посібник з перекладу WordPress RTL охоплює шаблони 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 — це не вибір найкращої моделі ШІ. Йдеться про дотримання структурних правил формату: інтерполяції, суфікси множинної форми, вкладені ключі та HTML-теги повинні витримати весь цикл. Споживчі інструменти ШІ розглядають JSON як неструктурований текст. Синтаксично-орієнтовані інструменти аналізують його як структуровані дані та торкаються лише поверхонь, що підлягають перекладу.

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

Готові безпечно перекладати свої JSON-файли i18next? Спробуйте SimplePoTranslate безкоштовно — кредитна картка не потрібна. Завантажте один раз, випустіть 41 мовою.