Jak přeložit jazykový soubor JSON bez poškození klíčů nebo zástupných symbolů

Chcete-li přeložit jazykový soubor JSON, například en.json, předejte celý soubor překladači, který rozumí JSONu. Vkládání surového textu do chatovacího okna nebo webového překladače je riskantní způsob. Překladač, který rozumí JSONu, soubor načte, přeloží pouze textové hodnoty a zapíše stejné klíče zpět, takže vaše aplikace může soubor stále načíst. Kopírování a vkládání může přeložit klíč, změnit uvozovky nebo vynechat složenou závorku. Cokoli z toho soubor poškodí.

Zachování klíčů je ta snadná část. Většina potíží přichází potom: zástupný symbol {name}, který se vrátí jako {nom}, ICU plurál, který ztratí svůj případ other, URL adresa odeslaná k překladu jako jakýkoli jiný text a několik změn, které překladač provede v samotném souboru. Těm se věnuje tato příručka.

Vytvořili jsme testovací soubor, který obsahuje všechny tyto případy, a napsali jsme bezplatný kontrolní nástroj, který porovnává zdrojový soubor s jeho překladem. Také jsme testovací soubor prohnali lokální kopií kódu pro parsování a zápis JSONu, který používá BookTranslator, s markerem místo modelu, abyste přesně viděli, které hodnoty se odesílají a jak se soubor vrací.

Rychlá odpověď: Co se stane s jednotlivými částmi souboru

Zbytek této příručky ukazuje, odkud každý řádek pochází a co s ním dělat.

Krok 1: Zkontrolujte zdrojový soubor před nahráním

Spusťte kontrolní nástroj na soubor, který plánujete přeložit. Potřebuje Python 3 a nic jiného:

python3 check_i18n_json.py en.json

U našeho testovacího souboru vypsal:

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

Dvě varování a poznámka o klíčích podobných celým číslům odpovídají každá jedné změně, kterou jsme viděli, když náš testovací soubor prošel překladačem. Pokud váš soubor nevykáže žádnou z nich, můžete přejít ke kroku 3.

Kontrolní nástroj také odmítne soubor, který není striktní JSON, například soubor s komentáři nebo čárkami na konci, protože to je další problém.

Co se vrátilo z našeho testovacího souboru

Test proběhl 2. listopadu 2026 proti aktuálnímu zpracování JSON v backendu BookTranslatoru. Místo volání modelu test nahradil každou hodnotu, která by byla odeslána k překladu, textem [ZH] plus původní text. Díky tomu je výsledek předvídatelný: cokoli s předponou [ZH] bylo odesláno, cokoli bez ní nikoli. Oba výstupy jsou zveřejněny: přeložený soubor a dvojjazyčný soubor.

Přeložený soubor

Každý klíč se vrátil nezměněný a soubor se stále načetl. Hodnoty s písmeny byly odeslány, včetně {name}, %s, zprávy ICU, značky <b> a adresy URL nápovědy. Řetězec verze "2.4.1", pomlčka a prázdný řetězec odeslány nebyly, protože neobsahují žádná písmena. Čísla a booleovské hodnoty zůstaly nedotčeny.

Změnily se čtyři další věci:

1. Jeden řetězec se dostal do nesprávného klíče. V našem testu měl soubor plochý klíč "error.network" s textem „Zkontrolujte připojení.“ a také vnořený "error": { "network": "Network error" }. Překladač identifikuje každý řetězec podle jeho cesty s tečkami mezi částmi, takže oba řetězce měly stejnou adresu error.network. Ve výstupu oba klíče obsahovaly překlad „Chyba sítě“. „Zkontrolujte připojení.“ zmizelo. To vyžaduje oba styly v jednom souboru, což je vzácné, ale selhává to tiše. Kontrolor na to upozorní před nahráním.
2. Klíče podobné celým číslům byly přeuspořádány. "steps": { "10": ..., "2": ..., "1": ... } se vrátilo jako "1", "2", "10". JavaScript vždy při sestavování objektu uvádí klíče podobné celým číslům jako první, v číselném pořadí. Klíče a hodnoty stále odpovídají, takže vaše aplikace je v pořádku, ale rozdílový výpis proti zdrojovému souboru bude nepřehledný.
3. Velké ID ztratilo přesnost. 9007199254740993 se vrátilo jako 9007199254740992. JavaScript ukládá čísla jako 64bitová čísla s plovoucí desetinnou čárkou a celá čísla nad 2^53 nelze všechna přesně reprezentovat (MDN o Number.MAX_SAFE_INTEGER). Dlouhá ID ukládejte jako řetězce nebo je v jazykovém souboru vůbec nemějte.
4. Formátování bylo přepsáno. Výstup používá dvoumezerové odsazení a končí novým řádkem. Pokud váš zdroj používal tabulátory nebo čtyři mezery, očekávejte v rozdílovém výpisu změny bílých znaků.

Náš testovací soubor neměl žádné duplicitní klíče, ale stojí za to o nich vědět: JavaScriptový JSON parser uchová pouze poslední hodnotu pro opakovaný klíč, takže dřívější text se nikdy nepřeloží. Vaše aplikace by načetla stejnou poslední hodnotu, takže viditelně se nic nerozbije, ale kontrolor vypíše duplicitní klíče, abyste je mohli vyčistit.

Dvojjazyčný soubor

Dvojjazyčný soubor zachová každou původní hodnotu a přidá sourozenecký klíč s příponou _translated:

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

To se dobře hodí pro revizi, protože zdroj a překlad jsou vedle sebe. Není to však soubor, který by vaše aplikace mohla načíst, protože každý klíč má nyní dvojče. V aplikaci používejte přeložený soubor.

Jedna mezera: řetězce uvnitř polí nedostanou sourozenecký klíč _translated, protože položky pole nemají klíč, ke kterému by se dal přidat. V našem testu se "menu": ["Open", "Save", "Export as EPUB"] vrátilo v dvojjazyčném souboru anglicky, ale v přeloženém souboru přeložené. Pokud revidujete z dvojjazyčného souboru, zkontrolujte pole v přeloženém souboru.

Soubory s komentáři

Mnoho projektů uchovává komentáře ve svých jazykových souborech (JSONC), což striktní JSON neumožňuje. Překladač nejprve zkusí striktní JSON. Pokud to selže, odstraní komentáře a koncové čárky a zkusí to znovu. Odstranění komentářů znamená smazání všeho za // na řádku, a to včetně // v https://.

Náš soubor s komentářem a URL se vůbec nenačetl; parsování selhalo na prvním komentáři. Soubor s komentáři, ale bez // uvnitř žádné hodnoty, se načetl v pořádku a komentáře byly z výstupu odstraněny.

Takže: pokud váš soubor obsahuje komentáře, před nahráním je odstraňte, nebo si ponechte kopii s komentáři a smiřte se s tím, že překlad je nebude mít.

Krok 2: Příprava souboru

Většinu těchto problémů můžete vyřešit před překladem:

• Převeďte na striktní JSON. Odstraňte komentáře a koncové čárky. Pokud váš nástroj pro sestavení čte JSONC, ponechte soubor s komentáři jako zdroj a pro překlad exportujte čistou kopii.
• Používejte jeden styl klíčů. Klíče buď vnořujte, nebo je zplošťujte tečkami, ne obojí v jednom souboru. Pokud používáte i18next, jeho volba keySeparator řídí, jak se tečky v klíčích čtou, takže toto nastavení zkontrolujte, než cokoli zploštíte.
• Přesuňte netextová data jinam. ID, URL, příznaky funkcí a limity patří do konfigurace, ne do jazykového souboru. Pokud URL musí zůstat, ponechte ji, ale počítejte s tím, že ji po překladu zkontrolujete. Náš průvodce nepřekládaným obsahem pokrývá, jak rozhodnout, co dalšího má zůstat v původním jazyce.
• Zástupné symboly pište všude stejně. Jeden styl, například {name}, se kontroluje snáze než směs {name}, {{name}} a %s.

Krok 3: Překlad celého souboru

Nahrajte vyčištěný soubor do překladače dokumentů BookTranslator, který uvádí .json mezi ostatními přijímanými lokalizačními a strukturovanými textovými formáty. Cena se zobrazí před platbou. Po dokončení úlohy vám stránka historie nabídne přeložený soubor a dvojjazyčný soubor jako samostatné soubory ke stažení.

Výsledek ovlivňují dvě věci týkající se překladu textu:

• Model nevidí vaše klíče. Každá hodnota je odeslána jako očíslovaný segment bez názvu klíče. Pokud "button.open" i "status.open" obsahují „Open“, model nemá jak poznat, že jedno je sloveso a druhé přídavné jméno. Krátké a nejednoznačné řetězce je třeba zkontrolovat ručně.
• Každá hodnota se překládá samostatně. Nic nespojuje dva klíče dohromady, takže stejné slovo na dvou místech může vyjít dvakrát jinak a slovo, které potřebuje dva různé překlady, může vyjít stejně. Volitelný automatický glosář BookTranslatoru shromažďuje názvy, místa a odborné termíny a udržuje je konzistentní, ale nemůžete mu zadat vlastní pevné překlady. U termínů, které musí být přeloženy jedním přesným způsobem, si veďte seznam termínů a tyto řetězce po překladu zkontrolujte; náš průvodce glosářem vysvětluje, jak takový seznam naplánovat.

Vložené HTML značky se po překladu počítají a segment, jehož značky nesouhlasí, se znovu zpracuje. Zástupné symboly ve složených závorkách, zástupné symboly ve stylu %s a syntaxe ICU se odesílají jako součást textu, ale nekontrolují se stejným způsobem. Proveďte krok 4 u každého překladu.

Pokud raději překládáte pomocí chatovacího modelu nebo lokálního modelu, posílejte pouze hodnoty, nikdy ne surový soubor, a skriptem je vraťte zpět podle klíčů. Níže uvedené kontroly platí v obou případech.

Krok 4: Zkontrolujte přeložený soubor

Porovnejte překlad se zdrojem:

python3 check_i18n_json.py en.json fr.json

Abychom ukázali, co odhalí, vytvořili jsme francouzský soubor s nasazenými chybami. Je ručně vytvořený, nejde o výstup modelu. Po stejných upozorněních ke zdroji jako v kroku 1 nástroj pro kontrolu vypsal:

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

Každá z těchto chyb by se v aplikaci projevila jako chyba: prázdné jméno, nefunkční odkaz, pád nebo surová zpráva při vykreslení množného čísla, chybějící počet kapitol, limit porovnávaný jako text. Řádek INFO uvádí řetězce, které se vrátily nezměněné. Některé jsou v pořádku, například názvy značek; „Save“ ve francouzské nabídce ale ne.

Nástroj pro kontrolu porovnává klíče, typy hodnot, netextové hodnoty, zástupné symboly ({name}, {{name}}, %s, %1$s, %@), názvy argumentů ICU, HTML značky a adresy URL. Sám překlad neposuzuje.

Případy množného čísla se mají měnit

ICU plural uvádí jednu zprávu pro každou kategorii množného čísla. Angličtina má dvě kategorie, one a other, ale mnoho jazyků má jinou sadu. Dobrý ruský překlad naší zprávy items by obvykle používal one, few, many a other, zatímco japonský pouze other. Nesoulad zde tedy není vždy chybou.

Kategorie pocházejí z pravidel množného čísla Unicode CLDR a other má každý jazyk. Toto jsou základní kategorie hlášené funkcí Intl.PluralRules v Node.js s CLDR 48:

Francouzština, španělština a portugalština používají many pouze pro velmi velká kulatá čísla, jako je milion, takže zpráva pro malé počty se bez něj obvykle obejde. Kontroler hlásí chybějící other jako chybu a jakoukoli jinou změnu kategorií jako varování k porovnání s touto tabulkou. Seznam pro jakýkoli jazyk si můžete vypsat sami:

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

Překladatel dostane anglické případy, takže zkontrolujte, co se vrátilo. Pokud má ruská nebo arabská zpráva stále jen one a other, doplňte chybějící případy ručně nebo to nechte udělat překladatele.

Poté jej načtěte v aplikaci

Kontroler prokáže, že soubor je bezpečné načíst, ne že se dobře čte. Přepněte aplikaci do nového jazyka a prohlédněte si obrazovky: dlouhá slova v němčině nebo finštině, která přetékají z tlačítek, text zprava doleva v arabštině nebo hebrejštině a data či čísla, která váš kód formátuje odděleně od jazykového souboru. Náš průvodce překladem versus lokalizací pokrývá, co dalšího se mezi trhy kromě slov mění.

Časté problémy

Přeložený soubor se v mé aplikaci nenačte. Spusťte na něj kontroler. Pokud jej kontroler nedokáže zpracovat, soubor byl po překladu upraven nebo nebyl platný už od začátku. Pokud se zpracuje, hledejte řádky ERROR týkající se klíčů nebo typů.

Řetězec se zobrazuje jako surová zpráva ICU, například {count, plural, ...}. Syntaxe ICU se při překladu porušila, obvykle chybějící složená závorka nebo chybějící případ other. Zkopírujte strukturu ze zdroje a přeložte pouze slova uvnitř jednotlivých případů.

Můj soubor je YAML, soubor .po nebo Markdown. BookTranslator přijímá i ty, ale každý formát má svá pravidla. Pro dokumentaci viz náš průvodce překladem Markdown; pro webové stránky průvodce soubory HTML.

Mohu přeložit pouze nové klíče? Ne v rámci jednoho nahrání; překládá se celý soubor. Vložte nové klíče do samostatného souboru, přeložte jej a výsledek slučte podle klíčů. Kontroler potvrdí, že sloučený soubor obsahuje všechny klíče.

Mám překládat klíče? Ne. Klíče jsou identifikátory, které váš kód vyhledává. Textem pro lidi jsou pouze hodnoty.