Jak přeložit i18next JSON soubory v Reactu a Next.js (2026)

Právě jste dokončili aplikaci v Reactu, která musí být do příštího pátku dostupná ve 12 jazycích. Vaše soubory lokálních nastavení se nacházejí v public/locales/en/common.json, máte 340 klíčů pro každé lokální nastavení a tokeny uvnitř vašich řetězců vypadají jako {{userName}} a {{count}} roztroušené napříč vnořenými objekty. Vložíte JSON do ChatGPT a vrátí se s {{ nombreUsuario }}, nadbytečnými mezerami a polovinou přejmenovaných klíčů pro množné číslo. Vaše aplikace selže při sestavení.

Pokud jste se pokusili automatizovat překlad i18next JSON, znáte tuto bolest. Formát JSON je flexibilní, a právě proto ho většina překladatelských nástrojů znetvoří. Skutečný problém není v kvalitě jazykového modelu – spočívá v tom, že spotřebitelské AI nástroje nerozumí strukturálním pravidlům i18next.

Tato příručka vysvětluje, čím se i18next JSON liší od ostatních formátů lokálních nastavení, proč naivní překladatelské přístupy narušují aplikace v Reactu a Next.js a jak bezpečně automatizovat překlad napříč desítkami lokálních nastavení bez ruční kontroly každého klíče.

Co je i18next JSON a proč je překlad zrádný

i18next je nejpoužívanější i18n knihovna v ekosystému JavaScriptu. Používají ji React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue a Node backend služby. Přeložitelné řetězce ukládá do plochých nebo vnořených JSON souborů, jeden pro každé lokální nastavení.

Typický soubor vypadá takto:

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

To vypadá jednoduše, ale tři věci činí překlad s univerzální AI nebezpečným.

Interpolace tokenů je strukturální, nikoli textová

Sekvence {{userName}} není slovo – je to zástupný symbol, který runtime nahradí daty. Přidáte-li mezeru ({{ userName }}), přejmenujete jej nebo přeložíte vnitřní identifikátor, runtime tiše selže nebo vyvolá chybu. Někteří překladatelé užitečně převedou {{count}} na {{conteo}} ve španělštině. Vaše aplikace se nyní pokusí interpolovat proměnnou, která neexistuje, a vykreslí nezpracovaný zástupný symbol uživateli.

Klíče pro množné číslo jsou magické sufixy

i18next detekuje množná čísla podle sufixů: _zero, _one, _two, _few, _many, _other. Nejedná se o libovolné řetězce – musí odpovídat kategoriím množného čísla CLDR pro cílové lokální nastavení. Angličtina používá pouze _one a _other. Ruština, arabština a polština používají až šest kategorií. Pokud váš překladatel vynechá _other nebo jej přejmenuje, řetězec záložních možností se přeruší.

Vnořené klíče musí zůstat nedotčené

Na rozdíl od Gettext .po souborů, které jsou plochými páry klíč-hodnota, se i18next soubory mohou vnořovat libovolně. Líný překladatel by mohl strukturu zploštit, změnit názvy klíčů tak, aby odpovídaly přeloženému textu, nebo přeskládat objekty. Vaše volání t('cart.items_other') v kódu se již nevyřeší.

Špatná řešení, která vývojáři zkouší jako první

Každý tým prochází stejným třífázovým cyklem selhání, než investuje do skutečného řešení.

Fáze jedna: Vložení do ChatGPT

Zkopírujete 200 klíčů do ChatGPT, zeptáte se „přelož toto JSON do španělštiny“ a výsledek vložíte zpět. Pro 180 klíčů to funguje. Dvacet má přidané mezery uvnitř {{...}}, tři mají přepsané sufixy pro množné číslo a jeden tag <strong> byl přeložen na <fuerte>. Vaše sestavení buď selže, nebo do produkce odešle tiše poškozené řetězce.

Fáze dvě: Google Translate API

Propojíte Google Translate REST API, iterujete přes váš JSON a odesíláte každou hodnotu. Rychlost je skvělá. Kvalita nikoli. API Googlu zpracovává každý řetězec izolovaně – bez kontextu o vaší aplikaci, bez pochopení, že {{count}} je zástupný symbol, bez vědomí, že klíč cart.empty se liší od cart.items_one. Stále potřebujete lidskou kontrolu každého klíče.

Fáze tři: Komerční TMS platformy

Zaregistrujete se u systému pro správu překladů. Účtují si za slovo, vyžadují integrace s GitHubem a zavazují vás k měsíčním poplatkům za uživatele. Pro vedlejší projekt nebo nezávislou aplikaci se ekonomika rychle zhroutí – a stále narazíte na stejné problémy s poškozením zástupných symbolů, pokud jejich engine konkrétně nerozpozná formát i18next.

Stejné režimy selhání se objevují i v Gettext pracovních postupech. Náš průvodce jak přeložit .po soubory bez narušení proměnných v kódu pokrývá paralelní problém pro WordPress a další Gettext-založené systémy.

Bezpečný přístup: Překlad s ohledem na syntaxi

Jediný spolehlivý způsob, jak překládat i18next JSON ve velkém měřítku, je pomocí nástroje, který nejprve analyzuje formát, uzamkne syntaxi a do AI odesílá pouze přeložitelný text.

Zde je, co zpracování s ohledem na syntaxi dělá pod kapotou:

1. Analyzuje JSON do abstraktního stromu, zachovává cesty klíčů a vnoření.
2. Identifikuje interpolační tokeny ({{name}}, {{count, number}}, {{date, datetime}}) a nahradí je ID zástupných symbolů.
3. Identifikuje HTML tagy uvnitř komponent Trans (<0>, <strong>, <br/>) a uzamkne je.
4. Detekuje klíče pro množné číslo podle sufixu a mapuje je na pravidla CLDR pro cílové lokální nastavení.
5. Odesílá pouze vyčištěný text do LLM s kontextem o cestě klíče.
6. Znovu vloží původní tokeny a tagy na jejich přesné pozice.
7. Ověří výstup – pokud chybí nebo je poškozený jakýkoli zástupný symbol, vrátí se k původnímu zdroji.

To je stejný princip, který zajišťuje bezpečnost cloudového překladu PO souborů. Pokud vás zajímá základní architektura, naše srovnání kvality překladu AI rozebírá, jak různé LLM modely zvládají tato omezení.

Krok za krokem: Překlad i18next JSON pomocí SimplePoTranslate

SimplePoTranslate podporuje i18next JSON nativně v plánech Pro a Lifetime. Bezplatná úroveň aktuálně pokrývá .po a .pot – upgradujte nebo použijte zkušební verzi pro přístup k JSON.

1. Připravte svůj zdrojový soubor

Použijte svůj anglický (nebo zdrojový) soubor lokálních nastavení jako hlavní. Ujistěte se, že je to platný JSON a obsahuje všechny klíče, které vaše aplikace používá. Častou chybou je ponechání zastaralých nebo nepoužívaných klíčů, což spotřebovává vaši překladatelskou kvótu na řetězce, které nikdy nezobrazíte.

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

2. Nahrání do SimplePoTranslate

Přihlaste se do svého panelu, klikněte na Nový překlad a nahrajte common.json. Platforma automaticky detekuje formát i18next. Vyberte si cílový jazyk z 41 podporovaných lokálních nastavení, zvolte tón (profesionální, neformální, marketingový) a odešlete.

3. Nechte pracovat engine

Pod kapotou je soubor analyzován, rozdělen do bezpečných dávek a překládán paralelně. Interpolační tokeny jsou uzamčeny. Sufixy pro množné číslo jsou zachovány a mapovány na pravidla CLDR cílového lokálního nastavení. HTML uvnitř komponent Trans zůstává nedotčeno.

4. Stáhněte ZIP

Obdržíte ZIP obsahující přeložený JSON a navíc alternativní formáty (.php pro PHP aplikace, .po pro kompatibilitu mezi nástroji). Vložte JSON do public/locales/es/common.json a znovu nasaďte aplikaci.

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

5. Opakování nebo dávkové zpracování

Pro všech 12 cílových lokálních nastavení odešlete 12 úloh. Kvóty Pro plánu pokrývají desítky typických SaaS aplikací. Pro monorepository s více soubory jmenných prostorů nahrajte každý samostatně nebo je zpracujte dávkově postupně.

Integrace překladů zpět do vaší aplikace

Jakmile máte přeložené JSON soubory, integrace je snadná část. Několik úskalí:

• Ověřte kategorie množného čísla. Pro každé lokální nastavení proveďte rychlý funkční test: vykreslete komponentu s count={0}, count={1}, count={5} a potvrďte, že všechny tři produkují správný řetězec.
• Zkontrolujte RTL lokální nastavení. Pokud jste překládali do arabštiny, hebrejštiny nebo perštiny, vaše UI potřebuje CSS s podporou RTL. Náš průvodce překladem WordPress RTL pokrývá vzory CSS, které platí i pro aplikace v Reactu.
• Nastavte záložní řetězec. Nakonfigurujte i18next tak, aby se v případě chybějícího klíče vrátil k angličtině, aby stavy během nasazení nezpůsobovaly pád uživatelům.
• Uzamkněte svůj zdrojový soubor v CI. Přidejte kontrolu, která odmítne PR, kde se změní en/common.json bez opětovného generování ostatních lokálních nastavení. Posun překladů je největší příčinou i18n chyb v produkci.

Pro týmy, které nasazují aplikace napříč Reactem, Next.js a server-side, je produkce každého formátu z jednoho zdroje obrovskou výhodou. Náš příspěvek o jednom souboru dovnitř, pěti formátech ven vysvětluje, proč je vícesložkový výstup důležitý pro dlouhodobou údržbu.

Když JSON nestačí: Řešení složitých případů

Několik okrajových případů vyžaduje zvláštní péči.

ICU MessageFormat

Pokud váš projekt používá syntaxi ICU ({count, plural, one {1 item} other {# items}}), i18next ji považuje za interpolaci, ale struktura je složitější. Ujistěte se, že váš překladatelský nástroj rozpoznává parametry ICU a nepřekládá názvy kategorií jako one, other nebo identifikátory formátu jako plural, number, date.

Komponenta Trans s React uzly

<Trans> vykresluje React komponenty uvnitř přeložených řetězců, indexovaných (<0>, <1>). Překladatel musí zachovat přesné pořadí tagů. Syntaxní zámek SimplePoTranslate to zvládá, ale pokud používáte jiný nástroj, ověřte to před nasazením.

Soubory jmenných prostorů

Velké aplikace rozdělují lokální nastavení do jmenných prostorů: common.json, dashboard.json, checkout.json. Každý soubor přeložte nezávisle – neslučujte je. Kvalita kontextu je vyšší, když cesty klíčů každého jmenného prostoru zůstanou v rozsahu.

Shrnutí

Překlad i18next JSON pro aplikaci v Reactu nebo Next.js není o výběru nejlepšího AI modelu. Je to o respektování strukturálních pravidel formátu: interpolace, sufixy pro množné číslo, vnořené klíče a HTML tagy musí přežít tam a zpět. Spotřebitelské AI nástroje považují JSON za nestrukturovaný text. Nástroje s ohledem na syntaxi jej analyzují jako strukturovaná data a dotýkají se pouze přeložitelných povrchů.

Pokud nasazujete vícejazyčnou aplikaci a kopírujete a vkládáte JSON do chatovacích rozhraní, už znáte cenu: hodiny ruční kontroly pro každé lokální nastavení, náhodné produkční chyby a rostoucí hromadu poškozených tvarů množného čísla. Potrubí s ohledem na formát odstraňuje každý z těchto režimů selhání.

Jste připraveni bezpečně přeložit své i18next JSON soubory? Vyzkoušejte SimplePoTranslate zdarma – není vyžadována kreditní karta. Nahrajte jednou, nasazujte ve 41 jazycích.