i18next JSON -tiedostojen kääntäminen React- ja Next.js-sovelluksissa (2026)

Olet juuri saanut valmiiksi React-sovelluksen, joka on saatava 12 kielellä jakeluun ensi perjantaihin mennessä. Paikallistiedostosi sijaitsevat osoitteessa public/locales/en/common.json, sinulla on 340 avainta paikallisversiota kohden, ja merkkijonojesi sisällä olevat tunnukset näyttävät {{userName}} ja {{count}} hajallaan sisäkkäisissä objekteissa. Liimaat JSON-tiedoston ChatGPT:hen, ja se palauttaa {{ nombreUsuario }}, ylimääräisiä välilyöntejä ja puolet monikkomuotoisten avaimista uudelleennimettyinä. Sovelluksesi kaatuu käännösvaiheessa.

Jos olet yrittänyt automatisoida i18next JSON -käännöstä, tunnet tämän tuskan. JSON-muoto on joustava, mikä on juuri syy siihen, miksi useimmat käännöstyökalut sottaavat sen. Todellinen ongelma ei ole kielimallin laatu – vaan se, että kuluttajaluokan tekoälytyökalut eivät ymmärrä i18nextin rakenteellisia sääntöjä.

Tämä opas käy läpi, mikä tekee i18next JSONista erilaisen kuin muista paikallistamismuodoista, miksi naiivit käännösmenetelmät rikkovat React- ja Next.js-sovelluksia, ja miten automatisoida käännökset turvallisesti kymmenille paikallisversioille ilman, että jokaista avainta tarkistetaan manuaalisesti.

Mitä i18next JSON on ja miksi kääntäminen on hankalaa

i18next on laajimmin käytetty i18n-kirjasto JavaScript-ekosysteemissä. Se pyörittää React- (react-i18next), Next.js- (next-i18next, App Router next-intl), Vue- ja Node-taustapalveluita. Se tallentaa käännettävät merkkijonot tasaisiin tai sisäkkäisiin JSON-tiedostoihin, yksi paikallisversiota kohden.

Tyypillinen tiedosto näyttää tältä:

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

Tämä näyttää yksinkertaiselta, mutta kolme asiaa tekevät siitä vaarallisen kääntää yleiskäyttöisellä tekoälyllä.

Interpolointimerkit ovat rakenteellisia, eivät tekstiä

Merkkijonoyhdistelmä {{userName}} ei ole sana – se on paikkamerkki, jonka suoritusympäristö korvaa tiedoilla. Jos lisäät välilyönnin ({{ userName }}), nimeät sen uudelleen tai käännät sisäisen tunnisteen, suoritusympäristö epäonnistuu hiljaisesti tai heittää virheen. Jotkut kääntäjät muuntavat avuliaasti {{count}} muotoon {{conteo}} espanjaksi. Sovelluksesi yrittää nyt interpoloida muuttujaa, jota ei ole olemassa, ja näyttää raaka-paikkamerkin käyttäjällesi.

Monikkomuotoiset avaimet ovat taikasuffikseja

i18next tunnistaa monikkomuodot suffiksien perusteella: _zero, _one, _two, _few, _many, _other. Nämä eivät ole mielivaltaisia merkkijonoja – niiden on vastattava kohdekielen CLDR-monikkomuotoja. Englanti käyttää vain _one ja _other. Venäjä, arabia ja puola käyttävät jopa kuutta luokkaa. Jos kääntäjäsi jättää pois _other tai nimeää sen uudelleen, palautusketju katkeaa.

Sisäkkäisten avaimien on säilyttävä ennallaan

Toisin kuin Gettextin .po-tiedostot, jotka ovat tasaisia avain-arvo-pareja, i18next-tiedostot voivat olla mielivaltaisesti sisäkkäisiä. Laiska kääntäjä saattaa litistää rakenteen, muuttaa avainten nimiä vastaamaan käännettyä tekstiä tai järjestellä objekteja uudelleen. Koodisi t('cart.items_other') -kutsu ei enää ratkea.

Huonot ratkaisut, joita kehittäjät kokeilevat ensin

Jokainen tiimi käy läpi saman kolmivaiheisen epäonnistumiskierron ennen kuin he investoivat todelliseen ratkaisuun.

Vaihe yksi: Liitä ChatGPT:hen

Kopioit 200 avainta ChatGPT:hen, kysyt "käännä tämä JSON espanjaksi" ja liität tuloksen takaisin. Se toimii 180 avaimella. Kahdessakymmenessä on ylimääräisiä välilyöntejä {{...}} sisällä, kolmen monikkomuodon suffiksit on kirjoitettu uudelleen, ja yksi <strong>-tagi on käännetty muotoon <fuerte>. Käännöksesi joko epäonnistuu tai lähettää hiljaisesti rikkinäisiä merkkijonoja tuotantoon.

Vaihe kaksi: Google Translate API

Kytket Google Translate REST API:n, iteroit JSON-tiedostosi läpi ja lähetät jokaisen arvon. Nopeus on hyvä. Laatu ei. Googlen API käsittelee jokaista merkkijonoa erikseen – ei kontekstia sovelluksestasi, ei ymmärrystä siitä, että {{count}} on paikkamerkki, ei tietoa siitä, että avain cart.empty eroaa avaimesta cart.items_one. Tarvitset silti ihmisen tarkistusta jokaiselle avaimelle.

Vaihe kolme: Kaupalliset TMS-alustat

Rekisteröidyt käännöstenhallintajärjestelmään. Ne veloittavat sanakohtaisesti, vaativat GitHub-integraatioita ja lukitsevat sinut kuukausittaisiin paikkoihin. Sivustoprojektissa tai indie-sovelluksessa taloudelliset edellytykset hajoavat nopeasti – ja kohtaat silti samat paikkamerkkien vioittumisongelmat, jos niiden moottori ei erikseen jäsenä i18next-muotoa.

Samat epäonnistumismoodit ilmenevät myös Gettext-työnkuluissa. Oppaamme kuinka kääntää .po-tiedostoja rikkomatta koodimuuttujia käsittelee rinnakkaista ongelmaa WordPressille ja muille Gettext-pohjaisille pinoille.

Turvallinen lähestymistapa: Syntaksista tietoinen käännös

Ainoa luotettava tapa kääntää i18next JSONia skaalassa on käyttää työkalua, joka jäsentää muodon ensin, lukitsee syntaksin ja lähettää vain käännettävän tekstin tekoälylle.

Tässä on, mitä syntaksista tietoinen käsittely tekee konepellin alla:

1. Jäsentää JSONin abstraktiksi puuksi, säilyttäen avainpolut ja sisäkkäisyyden.
2. Tunnistaa interpolointimerkit ({{name}}, {{count, number}}, {{date, datetime}}) ja korvaa ne paikkamerkki-ID:illä.
3. Tunnistaa HTML-tagit Trans-komponenttien sisällä (<0>, <strong>, <br/>) ja lukitsee ne.
4. Tunnistaa monikkomuotoiset avaimet suffiksin perusteella ja kartoittaa ne kohdekielen CLDR-sääntöihin.
5. Lähettää vain puhdistetun tekstin LLM:lle, mukana konteksti avainpolusta.
6. Lisää alkuperäiset merkit ja tagit takaisin niiden täsmällisiin paikkoihin.
7. Validoi tuloksen – jos jokin paikkamerkki puuttuu tai on virheellinen, palauttaa alkuperäiseen.

Tämä on sama periaate, joka tekee pilvipohjaisesta PO-käännöksestä turvallisen. Jos olet kiinnostunut taustalla olevasta arkkitehtuurista, tekoälykäännösten laatuvertailumme erittelee, miten eri LLM-mallit käsittelevät näitä rajoituksia.

Vaihe vaiheelta: Käännä i18next JSON SimplePoTranslatella

SimplePoTranslate tukee i18next JSONia natiivisti Pro- ja Lifetime-paketeissa. Ilmainen taso kattaa tällä hetkellä .po- ja .pot-tiedostot – päivitä tai käytä kokeiluversiota päästäksesi käsiksi JSONiin.

1. Valmistele lähdetiedosto

Käytä englanninkielistä (tai lähdekielen) tiedostoasi mestaritiedostona. Varmista, että se on kelvollinen JSON ja sisältää kaikki sovelluksesi käyttämät avaimet. Yleinen virhe on jättää vanhentuneet tai käyttämättömät avaimet, mikä kuluttaa käännöskiintiötäsi merkkijonoihin, joita et koskaan renderöi.

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

2. Lataa SimplePoTranslateen

Kirjaudu sisään hallintapaneeliisi, napsauta New Translation ja lataa common.json. Alusta tunnistaa automaattisesti i18next-muodon. Valitse kohdekieli 41 tuetusta paikallisversiosta, valitse sävy (ammattimainen, rento, markkinointi) ja lähetä.

3. Anna moottorin hoitaa työnsä

Konepellin alla tiedosto jäsennetään, pilkotaan turvallisiksi eriksi ja käännetään rinnakkain. Interpolointimerkit lukitaan. Monikkomuotoiset suffiksit säilytetään ja kartoitetaan kohdekielen CLDR-sääntöihin. Trans-komponenttien sisällä oleva HTML säilyy ennallaan.

4. Lataa ZIP-tiedosto

Saat takaisin ZIP-tiedoston, joka sisältää käännetyn JSONin sekä vaihtoehtoisia formaatteja (.php PHP-sovelluksille, .po työkalujen välisen yhteensopivuuden vuoksi). Pudota JSON tiedosto public/locales/es/common.json -polkuun ja julkaise uudelleen.

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

5. Toista tai eräajo

Kaikille 12 kohdekielelle lähetä 12 työtä. Pro-paketin kiintiöt kattavat kymmeniä tyypillisiä SaaS-sovelluksia. Monorepoissa, joissa on useita nimiavaruustiedostoja, lataa kukin erikseen tai suorita ne eräajona peräkkäin.

Käännösten integrointi takaisin sovellukseesi

Kun olet kääntänyt JSON-tiedostot, integrointi on helppoa. Muutama huomioitava asia:

• Varmista monikkomuotojen luokat. Suorita nopea savutesti jokaiselle paikallisversiolle: renderöi komponentti arvoilla count={0}, count={1}, count={5} ja varmista, että kaikki kolme tuottavat oikean merkkijonon.
• Tarkista oikealta vasemmalle kirjoitettavat kielet (RTL). Jos olet kääntänyt arabiaksi, hepreaksi tai persiaksi, käyttöliittymäsi tarvitsee RTL-tietoisen CSS:n. WordPress RTL -käännösopas käsittelee CSS-malleja, jotka soveltuvat myös React-sovelluksiin.
• Määritä palautusketju. Määritä i18next palautumaan englantiin, jos avain puuttuu, jotta käyttäjät eivät kohtaa kaatumisia käyttöönoton aikana.
• Lukitse lähdetiedostosi CI:ssä. Lisää tarkistus, joka hylkää PR:t, joissa en/common.json muuttuu ilman muiden paikalliskielien uudelleenluontia. Käännösten ero on ylivoimaisesti suurin syy tuotannon i18n-virheisiin.

Tiimeille, jotka julkaisevat React-, Next.js- ja palvelinpuolen kautta, jokaisen muodon tuottaminen yhdestä lähteestä on valtava voitto. Julkaisumme yksi tiedosto sisään, viisi muotoa ulos selittää, miksi monimuotoinen tulostus on tärkeää pitkän aikavälin ylläpidossa.

Kun JSON ei riitä: Monimutkaisten tapausten käsittely

Muutamat reunatapaukset vaativat erityistä huomiota.

ICU MessageFormat

Jos projektisi käyttää ICU-syntaksia ({count, plural, one {1 item} other {# items}}), i18next käsittelee sitä interpolointina, mutta rakenne on monimutkaisempi. Varmista, että käännöstyökalusi tunnistaa ICU-parametrit eikä käännä luokkien nimiä kuten one, other tai muototunnisteita kuten plural, number, date.

Trans-komponentti React-solmujen kanssa

<Trans> renderöi React-komponentteja käännettyjen merkkijonojen sisään, indeksoituina (<0>, <1>). Kääntäjän on säilytettävä tarkka tagien järjestys. SimplePoTranslaten syntaksilukitus hoitaa tämän, mutta jos käytät toista työkalua, tarkista ennen julkaisua.

Nimiavaruustiedostot

Suuret sovellukset jakavat paikalliskielet nimiavaruuksiin: common.json, dashboard.json, checkout.json. Käännä jokainen tiedosto itsenäisesti – älä yhdistä niitä. Kontekstin laatu on parempi, kun kunkin nimiavaruuden avainpolut pysyvät rajattuina.

Kaikki yhdessä

i18next JSONin kääntäminen React- tai Next.js-sovellukselle ei tarkoita parhaan tekoälymallin valitsemista. Kyse on muodon rakenteellisten sääntöjen kunnioittamisesta: interpolointien, monikkomuotoisten suffiksien, sisäkkäisten avainten ja HTML-tagien on kestettävä edestakainen matka. Kuluttajaluokan tekoälytyökalut käsittelevät JSONia jäsentämättömänä tekstinä. Syntaksista tietoiset työkalut jäsentävät sen jäsenneltynä datana ja koskevat vain käännettäviin pintoihin.

Jos toimitat monikielistä sovellusta ja olet kopioinut-liittänyt JSONia chat-käyttöliittymiin, tiedät jo kustannukset: tuntikausia manuaalista tarkistusta paikallisversiota kohden, satunnaisia tuotantovirheitä ja kasvavan pinon rikkinäisiä monikkomuotoja. Muototietoinen putki poistaa kaikki nämä virhetilat.

Oletko valmis kääntämään i18next JSON -tiedostosi turvallisesti? Kokeile SimplePoTranslatea ilmaiseksi – luottokorttia ei tarvita. Lataa kerran, julkaise 41 kielellä.