Hogyan fordítsuk i18next JSON fájlokat React és Next.js alkalmazásokban (2026)

Épp befejezte egy React alkalmazást, aminek jövő péntekre 12 nyelven kell megjelennie. A helyi fájljai a public/locales/en/common.json útvonalon találhatók, lokálénként 340 kulccsal rendelkezik, és a karaktersorozatokban található tokenek a {{userName}} és {{count}} formátumban jelennek meg, szétszórva a beágyazott objektumokban. Bemásolja a JSON-t a ChatGPT-be, és az {{ nombreUsuario }} értékkel, extra szóközökkel és a többes számú kulcsok felének átnevezésével tér vissza. Az alkalmazás összeomlik a buildelés során.

Ha már próbálta automatizálni az i18next JSON fordítást, ismeri ezt a problémát. A JSON formátum rugalmas, és pontosan ezért a legtöbb fordítóeszköz elferdíti. Az igazi probléma nem a nyelvi modell minősége – hanem az, hogy a fogyasztói szintű AI eszközök nem értik az i18next strukturális szabályait.

Ez az útmutató bemutatja, miben különbözik az i18next JSON a többi lokálé formátumtól, miért törnek össze a naiv fordítási megközelítések a React és Next.js alkalmazásokat, és hogyan lehet biztonságosan automatizálni a fordítást több tucat lokáléban anélkül, hogy manuálisan áttekintenénk minden kulcsot.

Mi az i18next JSON és miért bonyolult a fordítás

Az i18next a legszélesebb körben használt i18n könyvtár a JavaScript ökoszisztémában. Ez hajtja a React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue és Node backend szolgáltatásokat. A fordítható karaktersorozatokat lapos vagy beágyazott JSON fájlokban tárolja, lokálénként egyet.

Egy tipikus fájl így néz ki:

{
  "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>."
  }
}

Ez egyszerűnek tűnik, de három dolog miatt veszélyes általános célú AI-val fordítani.

Az interpolációs tokenek strukturálisak, nem szövegek

A {{userName}} sorozat nem egy szó – ez egy helyőrző, amelyet a futásidejű környezet adatokkal helyettesít. Adjon hozzá egy szóközt ({{ userName }}), nevezze át, vagy fordítsa le a belső azonosítót, és a futásidejű környezet csendesen hibázik vagy kivételt dob. Némely fordító segítőkészen {{count}}-t {{conteo}}-ra alakítja spanyolul. Alkalmazása most egy olyan változót próbál interpolálni, amely nem létezik, és a nyers helyőrzőt jeleníti meg a felhasználónak.

A többes számú kulcsok mágikus utótagok

Az i18next az utótagok alapján érzékeli a többes számokat: _zero, _one, _two, _few, _many, _other. Ezek nem tetszőleges karaktersorozatok – meg kell egyezniük a célnyelv CLDR többes szám kategóriáival. Az angol csak az _one és _other utótagokat használja. Az orosz, arab és lengyel akár hat kategóriát is használ. Ha a fordítója elhagyja vagy átnevezi az _other utótagot, a visszamenőleges lánc megszakad.

A beágyazott kulcsoknak érintetlenül kell maradniuk

Ellentétben a Gettext .po fájlokkal, amelyek lapos kulcs-érték párok, az i18next fájlok tetszőlegesen beágyazhatók. Egy lusta fordító laposíthatja a struktúrát, megváltoztathatja a kulcsneveket a fordított szöveghez igazítva, vagy átrendezheti az objektumokat. A t('cart.items_other') hívása a kódban már nem oldódik fel.

Rossz megoldások, amiket a fejlesztők először próbálnak

Minden csapat ugyanazon a három szakaszból álló hibacikluson megy keresztül, mielőtt befektetne egy valódi megoldásba.

Első szakasz: Beillesztés ChatGPT-be

200 kulcsot másol a ChatGPT-be, megkérdezi, hogy „translate this JSON to Spanish”, majd visszamásolja az eredményt. 180 kulcs esetében működik. Húsz kulcsban szóközök kerültek a {{...}} belsejébe, három kulcs többes számú utótagját átírták, és egy <strong> címke <fuerte>-re lett fordítva. A buildelés vagy sikertelen, vagy csendesen hibás karakterláncokat szállít éles környezetbe.

Második szakasz: Google Translate API

Beköti a Google Translate REST API-t, végigiterál a JSON fájlban, és elküldi minden értéket. A sebesség kiváló. A minőség azonban nem. A Google API minden karakterláncot elkülönítve kezel – nincs kontextus az alkalmazásáról, nincs megértése arról, hogy a {{count}} helyőrző, nincs tudatában annak, hogy a cart.empty kulcs különbözik a cart.items_one kulcstól. Továbbra is emberi felülvizsgálatra van szükség minden kulcs esetében.

Harmadik szakasz: Kereskedelmi TMS platformok

Feliratkozik egy fordításkezelő rendszerre. Szavanként díjat számolnak fel, GitHub integrációt igényelnek, és havi előfizetésre kényszerítik. Egy mellékprojekt vagy egy független alkalmazás esetében a gazdaságosság gyorsan összeomlik – és továbbra is ugyanazokkal a helyőrző-sérülési problémákkal szembesül, ha a motorjuk nem kifejezetten i18next formátumot elemzi.

Ugyanazok a hibamódok jelennek meg a Gettext munkafolyamatokban is. Az hogyan fordítsunk .po fájlokat kódváltozók megszakítása nélkül című útmutatónk a WordPress és más Gettext-alapú stack-ekkel kapcsolatos párhuzamos problémát tárgyalja.

A biztonságos megközelítés: szintaxis-érzékeny fordítás

Az i18next JSON nagyméretű fordításának egyetlen megbízható módja egy olyan eszköz, amely először elemzi a formátumot, lezárja a szintaxist, és csak a fordítható szöveget küldi az AI-nak.

Íme, mit csinál a szintaxis-érzékeny feldolgozás a háttérben:

1. Elemzi a JSON-t egy absztrakt fává, megőrizve a kulcsútvonalakat és a beágyazást.
2. Azonosítja az interpolációs tokeneket ({{name}}, {{count, number}}, {{date, datetime}}) és helyőrző azonosítókkal helyettesíti őket.
3. Azonosítja a Trans komponensekben található HTML címkéket (<0>, <strong>, <br/>) és lezárja azokat.
4. Érzékeli a többes számú kulcsokat utótagok alapján, és hozzárendeli azokat a célnyelv CLDR szabályaihoz.
5. Csak a megtisztított szöveget küldi az LLM-nek a kulcsútvonalra vonatkozó kontextussal.
6. Visszahelyezi az eredeti tokeneket és címkéket pontos pozíciójukba.
7. Érvényesíti a kimenetet – ha bármelyik helyőrző hiányzik vagy hibás, visszaállítja az eredetire.

Ez ugyanaz az elv, ami biztonságossá teszi a felhőalapú PO fordítást. Ha érdekli az alapul szolgáló architektúra, az AI fordítási minőség összehasonlításunk részletezi, hogyan kezelik a különböző LLM-ek ezeket a korlátokat.

Lépésről lépésre: i18next JSON fordítása SimplePoTranslate segítségével

A SimplePoTranslate natívan támogatja az i18next JSON-t Pro és Lifetime csomagokon. Az ingyenes szint jelenleg a .po és .pot fájlokat fedi le – frissítsen vagy használjon próbaverziót a JSON eléréséhez.

1. Készítse elő a forrásfájlt

Használja az angol (vagy forrásnyelv) fájlt mesterfájlként. Győződjön meg róla, hogy érvényes JSON, és tartalmazza az alkalmazása által használt összes kulcsot. Gyakori hiba az elavult vagy nem használt kulcsok meghagyása, ami a fordítási kvótát fogyasztja olyan karakterláncokra, amelyeket soha nem fog megjeleníteni.

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

2. Feltöltés a SimplePoTranslate-re

Jelentkezzen be az irányítópultjára, kattintson az Új fordítás gombra, és töltse fel a common.json fájlt. A platform automatikusan felismeri az i18next formátumot. Válassza ki a célnyelvet a 41 támogatott lokálé közül, válasszon hangnemet (professzionális, hétköznapi, marketing), majd küldje el.

3. Hagyja, hogy a motor dolgozzon

A háttérben a fájl elemzésre kerül, biztonságos kötegekre van bontva, és párhuzamosan fordítódik. Az interpolációs tokenek zárolva vannak. A többes számú utótagok megmaradnak, és a célnyelv CLDR szabályaihoz vannak rendelve. A Trans komponenseken belüli HTML érintetlen marad.

4. Töltse le a ZIP-et

Egy ZIP fájlt kap vissza, amely a lefordított JSON-t, valamint alternatív formátumokat (.php PHP alkalmazásokhoz, .po az eszközök közötti kompatibilitás érdekében) tartalmazza. Tegye a JSON-t a public/locales/es/common.json mappába, és telepítse újra.

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

5. Ismétlés vagy kötegelés

Mind a 12 célnyelvhez küldjön be 12 feladatot. A Pro csomag kvótái több tucat tipikus SaaS alkalmazást fedeznek. Több névterű fájllal rendelkező monorepo-k esetén töltse fel mindegyiket külön-külön, vagy kötegelje őket sorrendben.

Fordítások integrálása az alkalmazásba

Miután lefordította a JSON fájlokat, az integráció a könnyebb rész. Néhány buktató:

• Ellenőrizze a többes számú kategóriákat. Futtasson gyors füsttesztet lokálénként: rendereljen egy komponenst count={0}, count={1}, count={5} értékekkel, és győződjön meg róla, hogy mindhárom a megfelelő karakterláncot adja eredményül.
• Ellenőrizze az RTL lokálékat. Ha arabra, héberre vagy perzsára fordított, felhasználói felületének RTL-kompatibilis CSS-re van szüksége. A WordPress RTL fordítási útmutatónk ismerteti azokat a CSS mintákat, amelyek a React alkalmazásokra is érvényesek.
• Állítson be egy visszamenőleges láncot. Konfigurálja az i18next-et, hogy angolra essen vissza, ha egy kulcs hiányzik, így a telepítés közbeni állapotok nem okoznak összeomlást a felhasználóknak.
• Zárolja a forrásfájlt a CI-ben. Adjon hozzá egy ellenőrzést, amely elutasítja azokat a PR-eket, ahol az en/common.json fájl megváltozik anélkül, hogy más lokálék újragenerálódnának. A fordítási eltolódás az i18n hibák legnagyobb oka éles környezetben.

Azoknak a csapatoknak, amelyek React, Next.js és szerveroldali megoldásokat használnak, hatalmas előny, ha minden formátumot egy forrásból állítanak elő. Az egy fájl be, öt formátum ki című bejegyzésünk elmagyarázza, miért fontos a több formátumú kimenet a hosszú távú karbantartás szempontjából.

Amikor a JSON nem elég: komplex esetek kezelése

Néhány speciális eset extra figyelmet igényel.

ICU MessageFormat

Ha projektje ICU szintaxist használ ({count, plural, one {1 item} other {# items}}), az i18next interpolációként kezeli, de a struktúra bonyolultabb. Győződjön meg róla, hogy fordítóeszköze felismeri az ICU paramétereket, és nem fordítja le az olyan kategórianeveket, mint az one, other, vagy az olyan formátumazonosítókat, mint a plural, number, date.

Trans komponens React csomópontokkal

A <Trans> React komponenseket renderel a fordított karakterláncokon belül, index alapján kulcsolva (<0>, <1>). A fordítónak meg kell őriznie a pontos címkerendelést. A SimplePoTranslate szintaxiszárolása kezeli ezt, de ha másik eszközt használ, ellenőrizze a telepítés előtt.

Névtér fájlok

A nagy alkalmazások a lokálékat névterekre osztják: common.json, dashboard.json, checkout.json. Fordítson le minden fájlt külön-külön – ne egyesítse őket. A kontextus minősége magasabb, ha minden névtér kulcsútvonalai hatókörön belül maradnak.

Összefoglalás

Az i18next JSON fordítása React vagy Next.js alkalmazásokhoz nem a legjobb AI modell kiválasztásáról szól. Hanem a formátum strukturális szabályainak tiszteletben tartásáról: az interpolációknak, a többes számú utótagoknak, a beágyazott kulcsoknak és a HTML címkéknek túl kell élniük az oda-vissza utat. A fogyasztói AI eszközök a JSON-t strukturálatlan szövegként kezelik. A szintaxis-érzékeny eszközök strukturált adatként elemzik, és csak a fordítható felületeket érintik.

Ha többnyelvű alkalmazást szállít, és eddig JSON-t másolgatott be csevegőfelületekbe, már ismeri a költségét: órákig tartó manuális felülvizsgálat lokálénként, véletlenszerű éles hibák, és a hibás többes számú formák egyre növekvő halmaza. Egy formátum-érzékeny pipeline megszünteti ezeket a hibamódokat.

Készen áll, hogy biztonságosan lefordítsa i18next JSON fájljait? Próbálja ki ingyen a SimplePoTranslate-et – hitelkártya nélkül. Töltse fel egyszer, szállítsa 41 nyelven.