Kako prevesti JSON jezičnu datoteku bez razbijanja ključeva ili rezerviranih mjesta

Da biste preveli JSON jezičnu datoteku kao što je en.json, predajte cijelu datoteku prevoditelju koji razumije JSON. Lijepljenje sirovog teksta u chat prozor ili web prevoditelj rizičan je način. Prevoditelj koji razumije JSON čita datoteku, prevodi samo tekstualne vrijednosti i vraća iste ključeve, tako da vaša aplikacija i dalje može učitati datoteku. Kopiranje i lijepljenje može prevesti ključ, promijeniti navodnik ili izgubiti vitičastu zagradu. Bilo što od toga kvari datoteku.

Zadržavanje ključeva je laki dio. Većina problema dolazi poslije: rezervirano mjesto {name} koje se vrati kao {nom}, ICU množina koja izgubi svoj slučaj other, URL poslan na prijevod kao i svaki drugi tekst i nekoliko promjena koje prevoditelj napravi u samoj datoteci. To je ono što ovaj vodič pokriva.

Izradili smo testnu datoteku sa svakim od tih slučajeva i napisali besplatni provjerivač koji uspoređuje izvornu datoteku s njezinim prijevodom. Također smo testnu datoteku propustili kroz lokalnu kopiju koda za parsiranje i pisanje JSON-a koji koristi BookTranslator, s oznakom umjesto modela, kako biste točno vidjeli koje se vrijednosti šalju i kako se datoteka vraća.

Kratki odgovor: što se događa sa svakim dijelom datoteke

Ostatak ovog vodiča pokazuje odakle dolazi svaki redak i što učiniti u vezi s tim.

Korak 1: Provjerite izvornu datoteku prije prijenosa

Pokrenite alat za provjeru na datoteci koju planirate prevesti. Potreban je samo Python 3 i ništa više:

python3 check_i18n_json.py en.json

Na našoj testnoj datoteci ispisao je:

WARN  limits.projectId: 9007199254740993 is above 2^53 and can change in a JavaScript round trip; store IDs as strings
WARN  error.network: a flat key with dots and a nested key resolve to the same dot path; tools that address strings by dot path can mix them up
INFO  (root): 3 keys look like integers; JavaScript sorts those first and in numeric order when it rewrites the object
INFO  source: 17 strings, 2 numbers

Dva upozorenja i napomena o ključevima sličnim cijelim brojevima odgovaraju promjenama koje smo vidjeli kada je naša testna datoteka prošla kroz prevoditelj. Ako vaša datoteka ne dobije nijedno od njih, možete preskočiti na Korak 3.

Alat za provjeru također odbija datoteku koja nije strogi JSON, poput one s komentarima ili završnim zarezima, jer je to sljedeći problem.

Što se vratilo iz naše testne datoteke

Test je proveden 2. studenoga 2026. na trenutačnoj obradi JSON-a u BookTranslatorovom pozadinskom sustavu. Umjesto pozivanja modela, test je zamijenio svaku vrijednost koja bi bila poslana na prijevod s [ZH] plus izvorni tekst. To čini rezultat predvidljivim: sve što ima [ZH] ispred bilo je poslano, sve bez toga nije. Oba su izlaza objavljena: prevedena datoteka i dvojezična datoteka.

Prevedena datoteka

Svaki ključ vraćen je nepromijenjen, a datoteka se i dalje mogla parsirati. Poslane su vrijednosti sa slovima, uključujući {name}, %s, ICU poruku, oznaku <b> i URL pomoći. Verzija "2.4.1", crtica i prazan string nisu poslani jer ne sadrže slova. Brojevi i boolean vrijednosti ostavljeni su na miru.

Promijenile su se četiri druge stvari:

1. Jedan string završio je pod pogrešnim ključem. U našem testu datoteka je imala ravni ključ "error.network" s tekstom "Check your connection." i također ugniježđeni "error": { "network": "Network error" }. Prevoditelj svaki string identificira putanjom s točkama između dijelova, pa su oba stringa imala istu adresu, error.network. U izlazu su oba ključa sadržavala prijevod za "Network error". "Check your connection." je nestao. To zahtijeva oba stila u istoj datoteci, što je rijetko, ali ne uspijeva tiho. Provjera upozorava na to prije učitavanja.
2. Ključevi slični cijelim brojevima preuređeni su. "steps": { "10": ..., "2": ..., "1": ... } vratio se kao "1", "2", "10". JavaScript uvijek prvo navodi ključeve slične cijelim brojevima, numeričkim redoslijedom, kada ponovno gradi objekt. Ključevi i vrijednosti i dalje se podudaraju, pa je vaša aplikacija u redu, ali diff u odnosu na izvornu datoteku bit će bučan.
3. Veliki ID izgubio je preciznost. 9007199254740993 vratio se kao 9007199254740992. JavaScript pohranjuje brojeve kao 64-bitne floating point vrijednosti, a cijeli brojevi iznad 2^53 ne mogu se svi točno predstaviti (MDN o Number.MAX_SAFE_INTEGER). Duge ID-ove pohranite kao stringove ili ih držite izvan jezične datoteke.
4. Formatiranje je prepisano. Izlaz koristi uvlačenje od dva razmaka i završava novim redom. Ako je vaš izvor koristio tabulatore ili četiri razmaka, očekujte promjene bjelina u diffu.

Naša testna datoteka nije imala duplicirane ključeve, ali vrijedi ih znati: JavaScriptov JSON parser zadržava samo posljednju vrijednost za ponovljeni ključ, pa se raniji tekst nikada ne prevodi. Vaša aplikacija učitala bi istu posljednju vrijednost, pa ništa vidljivo ne puca, ali provjera navodi duplicirane ključeve kako biste ih mogli očistiti.

Dvojezična datoteka

Dvojezična datoteka čuva svaku izvornu vrijednost i dodaje susjedni ključ s _translated na kraju:

"greeting": "Welcome back, {name}!",
"greeting_translated": "[ZH] Welcome back, {name}!",

To dobro funkcionira za pregled jer izvor i prijevod stoje jedan uz drugi. To nije datoteka koju vaša aplikacija može učitati jer svaki ključ sada ima blizanca. U aplikaciji koristite prevedenu datoteku.

Jedan nedostatak: stringovi unutar polja ne dobivaju susjedni _translated jer stavke polja nemaju ključ kojem bi se dodao. U našem testu, "menu": ["Open", "Save", "Export as EPUB"] vratio se na engleskom u dvojezičnoj datoteci, ali preveden u prevedenoj datoteci. Ako pregledavate iz dvojezične datoteke, provjerite polja u prevedenoj datoteci.

Datoteke s komentarima

Mnogi projekti drže komentare u svojim jezičnim datotekama (JSONC), što strogi JSON ne dopušta. Prevoditelj prvo pokušava strogi JSON. Ako to ne uspije, uklanja komentare i završne zareze i pokušava ponovno. Uklanjanje komentara znači brisanje svega nakon // u retku, a to uključuje i // u https://.

Naša datoteka s komentarom i URL-om uopće se nije učitala; parsiranje je palo na prvom komentaru. Datoteka s komentarima, ali bez // unutar bilo koje vrijednosti, učitala se bez problema, a komentari su izbačeni iz izlaza.

Dakle: ako vaša datoteka ima komentare, uklonite ih prije učitavanja ili sačuvajte kopiju s komentarima i prihvatite da ih prijevod neće imati.

Korak 2: Pripremite datoteku

Većinu ovih problema možete riješiti prije prijevoda:

• Neka bude strogi JSON. Uklonite komentare i završne zareze. Ako vaš alat za izgradnju čita JSONC, sačuvajte datoteku s komentarima kao izvor i izvezite čistu kopiju za prijevod.
• Koristite jedan stil ključeva. Ili ugnijezdite ključeve ili ih spljoštite s točkama, ne oboje u istoj datoteci. Ako koristite i18next, njegova opcija keySeparator kontrolira kako se čitaju točke u ključevima, pa provjerite tu postavku prije nego što bilo što spljoštite.
• Premjestite netekstualne podatke van. ID-ovi, URL-ovi, feature flagovi i ograničenja pripadaju u konfiguraciju, ne u jezičnu datoteku. Ako URL mora ostati, zadržite ga, ali očekujte da ćete ga provjeriti nakon prijevoda. Naš vodič o tome što ne prevoditi pokriva kako odlučiti što još treba ostati na izvornom jeziku.
• Pišite placeholdere na isti način svugdje. Jedan stil, poput {name}, lakše je provjeriti od mješavine {name}, {{name}} i %s.

Korak 3: Prevedite cijelu datoteku

Učitajte očišćenu datoteku u BookTranslatorov prevoditelj dokumenata, koji navodi .json među ostalim formatima lokalizacije i strukturiranog teksta koje prihvaća. Cijena se prikazuje prije plaćanja. Kada zadatak završi, vaša stranica povijesti nudi prevedenu datoteku i dvojezičnu datoteku kao zasebna preuzimanja.

Dvije stvari u vezi s načinom na koji se tekst prevodi utječu na rezultat:

• Model ne vidi vaše ključeve. Svaka vrijednost šalje se kao numerirani segment, bez naziva ključa. Ako "button.open" i "status.open" oba glase "Open", model nema načina znati da je jedno glagol, a drugo pridjev. Kratki, dvosmisleni nizovi su oni koje treba ručno provjeriti.
• Svaka vrijednost prevodi se zasebno. Ništa ne povezuje dva ključa, pa se ista riječ na dva mjesta može vratiti na dva različita načina, a riječ koja zahtijeva dva različita prijevoda može se vratiti ista. BookTranslatorov neobavezni automatski pojmovnik prikuplja imena, mjesta i stručne termine i održava ih dosljednima, ali mu ne možete dati vlastite fiksne prijevode. Za termine koji se moraju prevesti na točno jedan način, vodite popis termina i provjerite te nizove nakon prijevoda; naš vodič za pojmovnik objašnjava kako ga planirati.

Umetnuti HTML oznake broje se nakon prijevoda, a segment čije se oznake ne podudaraju ponovno se pokušava prevesti. Zamjenski znakovi u vitičastim zagradama, zamjenski znakovi u stilu %s i ICU sintaksa šalju se kao dio teksta, ali ne provjeravaju se na isti način. Pokrenite 4. korak na svakom prijevodu.

Ako radije prevodite pomoću chat modela ili lokalnog modela, pošaljite samo vrijednosti, nikada sirovu datoteku, i vratite ih natrag po ključevima pomoću skripte. Provjere u nastavku vrijede u oba slučaja.

4. korak: Provjerite prevedenu datoteku

Usporedite prijevod s izvornikom:

python3 check_i18n_json.py en.json fr.json

Da pokažemo što otkriva, izradili smo francusku datoteku s podmetnutim pogreškama. Izrađena je ručno, nije rezultat modela. Nakon istih upozorenja o izvorniku kao u 1. koraku, provjerivač je ispisao:

ERROR app.greeting: placeholders differ; lost ['name'] extra ['nom']
ERROR app.help_url: urls differ; lost ['https://example.com/help'] extra ['https://example.com/aide']
ERROR app.items: ICU message has no 'other' case
ERROR app.legacy: placeholders differ; lost ['%d'] extra []
ERROR limits.maxFiles: type changed from int to str
ERROR limits.projectId: non-text value changed: 9007199254740993 -> 9007199254740992
INFO  menu[1]: identical to source: 'Save'
INFO  compared 20 source values, 1 unchanged strings

Svaka od njih pokazala bi se kao bug u aplikaciji: prazno ime, neispravna poveznica, pad ili sirova poruka kad se prikaže množina, nedostajući broj poglavlja, ograničenje uspoređeno kao tekst. Redak INFO navodi nizove koji su vraćeni nepromijenjeni. Neki su u redu, poput naziva robnih marki; "Save" u francuskom izborniku nije.

Provjerivač uspoređuje ključeve, vrste vrijednosti, ne-tekstualne vrijednosti, zamjenske znakove ({name}, {{name}}, %s, %1$s, %@), nazive ICU argumenata, HTML oznake i URL-ove. Ne ocjenjuje sam prijevod.

Padeži množine trebaju se mijenjati

ICU množina navodi jednu poruku po kategoriji množine. Engleski ima dvije kategorije, one i other, ali mnogi jezici imaju drugačiji skup. Dobar ruski prijevod naše poruke items obično bi koristio one, few, many i other, a japanski samo other. Stoga neslaganje ovdje nije uvijek pogreška.

Kategorije dolaze iz Unicode CLDR pravila za množinu, a other je ona koju ima svaki jezik. Ovo su kardinalne kategorije koje prijavljuje Intl.PluralRules u Node.js s CLDR 48:

Francuski, španjolski i portugalski koriste many samo za vrlo velike okrugle brojeve, poput milijuna, pa poruka za male brojeve obično može bez njega. Provjeravač prijavljuje nedostatak other kao pogrešku, a svaku drugu promjenu kategorija kao upozorenje za usporedbu s ovom tablicom. Popis za bilo koji jezik možete sami ispisati:

node -e 'console.log(new Intl.PluralRules("ru").resolvedOptions().pluralCategories)'

Prevoditelj dobiva engleske padeže, pa provjerite što je vraćeno. Ako ruska ili arapska poruka još uvijek ima samo one i other, ručno dodajte nedostajuće padeže ili to prepustite prevoditelju.

Zatim je učitajte u aplikaciju

Provjeravač dokazuje da je datoteka sigurna za učitavanje, a ne da se dobro čita. Prebacite aplikaciju na novi jezik i pregledajte zaslone: duge riječi u njemačkom ili finskom koje prelijevaju gumb, tekst s desna na lijevo u arapskom ili hebrejskom te datume ili brojeve koje vaš kod oblikuje odvojeno od jezične datoteke. Naš vodič kroz razliku između prevođenja i lokalizacije pokriva što se još mijenja između tržišta osim riječi.

Česti problemi

Prevedena datoteka neće se učitati u mojoj aplikaciji. Pokrenite provjeravač na njoj. Ako je provjeravač ne može parsirati, datoteka je uređivana nakon prevođenja ili u početku nije bila valjana. Ako se parsira, potražite retke ERROR o ključevima ili tipovima.

Niz se prikazuje kao sirova ICU poruka, poput {count, plural, ...}. ICU sintaksa se slomila tijekom prevođenja, obično zbog nedostajuće vitičaste zagrade ili nedostajućeg padeža other. Kopirajte strukturu iz izvornika i prevedite samo riječi unutar svakog padeža.

Moja datoteka je YAML, .po datoteka ili Markdown. BookTranslator prihvaća i njih, ali svaki format ima svoja pravila. Za dokumentaciju pogledajte naš vodič za prevođenje Markdowna; za web-stranice, vodič za HTML datoteke.

Mogu li prevesti samo nove ključeve? Ne unutar jednog učitavanja; prevodi se cijela datoteka. Stavite nove ključeve u zasebnu datoteku, prevedite je i spojite rezultat po ključu. Provjeravač će potvrditi da spojena datoteka ima svaki ključ.

Treba li prevoditi ključeve? Ne. Ključevi su identifikatori koje vaš kod traži. Samo su vrijednosti tekst za čitanje.