Cum să traduci fișiere i18next JSON în React & Next.js (2026)

Tocmai ai finalizat o aplicație React care trebuie livrată în 12 limbi până vinerea viitoare. Fișierele tale locale se află în public/locales/en/common.json, ai 340 de chei per localitate, iar token-urile din șirurile tale arată ca {{userName}} și {{count}} împrăștiate prin obiecte imbricate. Când inserezi JSON-ul în ChatGPT, primești înapoi {{ nombreUsuario }}, spații suplimentare și jumătate din cheile de pluralizare redenumite. Aplicația ta se blochează la compilare.

Dacă ai încercat să automatizezi traducerea i18next JSON, știi această durere. Formatul JSON este flexibil, motiv pentru care majoritatea instrumentelor de traducere îl distorsionează. Adevărata problemă nu este calitatea modelului lingvistic – este faptul că instrumentele AI de uz general nu înțeleg regulile structurale ale i18next.

Acest ghid detaliază ce face i18next JSON diferit de alte formate locale, de ce abordările naive de traducere strică aplicațiile React și Next.js și cum să automatizezi traducerea în siguranță pentru zeci de localizări fără a revizui manual fiecare cheie.

Ce este i18next JSON și de ce traducerea este dificilă

i18next este cea mai utilizată bibliotecă i18n din ecosistemul JavaScript. Aceasta stă la baza React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue și a serviciilor backend Node. Stochează șirurile de text traductibile în fișiere JSON plate sau imbricate, câte unul pentru fiecare localitate.

Un fișier tipic arată astfel:

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

Acest lucru pare simplu, dar trei aspecte îl fac periculos de tradus cu un AI de uz general.

Token-urile de interpolare sunt structurale, nu textuale

Secvența {{userName}} nu este un cuvânt – este un placeholder pe care runtime-ul îl înlocuiește cu date. Dacă adaugi un spațiu ({{ userName }}), îl redenumești sau traduci identificatorul intern, runtime-ul eșuează silențios sau generează o eroare. Unii traducători convertesc cu amabilitate {{count}} în {{conteo}} în spaniolă. Aplicația ta încearcă acum să interpoleze o variabilă care nu există și afișează placeholder-ul brut utilizatorului tău.

Cheile de pluralizare sunt sufixe „magice”

i18next detectează pluralurile prin sufixe: _zero, _one, _two, _few, _many, _other. Acestea nu sunt șiruri de caractere arbitrare – ele trebuie să corespundă categoriilor de plural CLDR pentru localitatea țintă. Engleza folosește doar _one și _other. Rusa, araba și poloneza folosesc până la șase categorii. Dacă traducătorul tău omite _other sau îl redenumește, lanțul de fallback se rupe.

Cheile imbricate trebuie să rămână intacte

Spre deosebire de fișierele Gettext .po, care sunt perechi cheie-valoare plate, fișierele i18next pot fi imbricate arbitrar. Un traducător leneș ar putea aplatiza structura, schimba numele cheilor pentru a se potrivi cu textul tradus sau reordona obiectele. Apelul tău t('cart.items_other') din cod nu se mai rezolvă.

Soluții greșite pe care dezvoltatorii le încearcă inițial

Fiecare echipă parcurge același ciclu de eșec în trei etape înainte de a investi într-o soluție reală.

Etapa întâi: Copiere în ChatGPT

Copiezi 200 de chei în ChatGPT, ceri „traduce acest JSON în spaniolă” și inserezi rezultatul înapoi. Funcționează pentru 180 de chei. Douăzeci au spații adăugate în interiorul {{...}}, trei au sufixe de plural rescrise și un tag <strong> a fost tradus în <fuerte>. Compilarea ta eșuează sau trimite șiruri de caractere defecte, dar silențios, în producție.

Etapa a doua: Google Translate API

Conectezi Google Translate REST API, iterezi peste JSON-ul tău și trimiți fiecare valoare. Viteza este excelentă. Calitatea nu. API-ul Google tratează fiecare șir de caractere izolat – fără context despre aplicația ta, fără a înțelege că {{count}} este un placeholder, fără a ști că cheia cart.empty este diferită de cart.items_one. Ai nevoie în continuare de o revizuire umană pentru fiecare cheie.

Etapa a treia: Platforme TMS comerciale

Te înregistrezi la un sistem de management al traducerilor. Acesta taxează pe cuvânt, necesită integrări GitHub și te blochează cu abonamente lunare. Pentru un proiect personal sau o aplicație indie, economia se prăbușește rapid – și tot te confrunți cu aceleași probleme de corupere a placeholder-urilor dacă motorul lor nu analizează specific formatul i18next.

Aceleași moduri de eșec apar și în fluxurile de lucru Gettext. Ghidul nostru despre cum să traduci fișiere .po fără a strica variabilele de cod acoperă problema paralelă pentru WordPress și alte stack-uri bazate pe Gettext.

Abordarea sigură: Traducerea conștientă de sintaxă

Singura modalitate fiabilă de a traduce i18next JSON la scară largă este cu un instrument care analizează mai întâi formatul, blochează sintaxa și trimite doar textul traductibil către AI.

iată ce face procesarea conștientă de sintaxă sub capotă:

1. Analizează JSON-ul într-un arbore abstract, păstrând căile cheilor și imbricarea.
2. Identifică token-urile de interpolare ({{name}}, {{count, number}}, {{date, datetime}}) și le înlocuiește cu ID-uri placeholder.
3. Identifică tag-urile HTML din componentele Trans (<0>, <strong>, <br/>) și le blochează.
4. Detectează cheile de plural prin sufix și le mapează la regulile CLDR pentru localitatea țintă.
5. Trimite doar textul curățat către LLM cu context despre calea cheii.
6. Reintroduce token-urile și tag-urile originale în pozițiile lor exacte.
7. Validează rezultatul – dacă un placeholder lipsește sau este deformat, revine la sursă.

Acesta este același principiu care face sigură traducerea PO bazată pe cloud. Dacă ești curios despre arhitectura subiacentă, comparația noastră de calitate a traducerii AI detaliază cum gestionează diferite LLM-uri aceste constrângeri.

Pas cu pas: Traducerea i18next JSON cu SimplePoTranslate

SimplePoTranslate suportă i18next JSON nativ pe planurile Pro și Lifetime. Nivelul gratuit acoperă în prezent .po și .pot – upgradează sau folosește o perioadă de încercare pentru a accesa JSON.

1. Pregătește fișierul sursă

Folosește fișierul tău în engleză (sau localitatea sursă) ca fișier master. Asigură-te că este un JSON valid și că conține toate cheile pe care le folosește aplicația ta. O greșeală comună este lăsarea cheilor vechi sau neutilizate, ceea ce îți consumă cota de traducere pentru șiruri de caractere pe care nu le vei randa niciodată.

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

2. Încarcă pe SimplePoTranslate

Conectează-te la panoul de control, dă clic pe New Translation și încarcă common.json. Platforma detectează automat formatul i18next. Alege limba țintă din cele 41 de localități suportate, selectează un ton (profesional, casual, marketing) și trimite.

3. Lasă motorul să lucreze

Sub capotă, fișierul este analizat, împărțit în loturi sigure și tradus în paralel. Token-urile de interpolare sunt blocate. Sufixele de plural sunt păstrate și mapate la regulile CLDR ale localității țintă. Codul HTML din componentele Trans rămâne intact.

4. Descarcă arhiva ZIP

Primești înapoi un fișier ZIP care conține JSON-ul tradus plus formate alternative (.php pentru aplicațiile PHP, .po pentru compatibilitate între instrumente). Plasează JSON-ul în public/locales/es/common.json și redeploiează.

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

5. Repetă sau Procesează în lot

Pentru toate cele 12 localizări țintă, trimite 12 sarcini. Cotele planului Pro acoperă zeci de aplicații SaaS tipice. Pentru monorepo-uri cu mai multe fișiere namespace, încarcă-le pe fiecare separat sau procesează-le secvențial în loturi.

Integrarea traducerilor înapoi în aplicația ta

Odată ce ai fișierele JSON traduse, integrarea este partea ușoară. Câteva aspecte de reținut:

• Verifică categoriile de plural. Rulează un test rapid per localitate: randează o componentă cu count={0}, count={1}, count={5} și confirmă că toate trei produc șirul corect.
• Verifică localizările RTL. Dacă ai tradus în arabă, ebraică sau persană, interfața ta are nevoie de CSS conștient de RTL. Ghidul nostru de traducere WordPress RTL acoperă tiparele CSS care se aplică și aplicațiilor React.
• Configurează un lanț de fallback. Configurează i18next să revină la engleză dacă lipsește o cheie, astfel încât stările intermediare de implementare să nu blocheze utilizatorii.
• Blochează fișierul sursă în CI. Adaugă o verificare care respinge PR-urile în care en/common.json se modifică fără a regenera alte localizări. Divergența traducerilor este cea mai mare cauză a bug-urilor i18n în producție.

Pentru echipele care livrează pentru React, Next.js și partea de server, producerea fiecărui format dintr-o singură sursă este un câștig imens. Articolul nostru despre un fișier la intrare, cinci formate la ieșire explică de ce ieșirea multi-format contează pentru întreținerea pe termen lung.

Când JSON nu este suficient: Gestionarea cazurilor complexe

Câteva cazuri extreme necesită o atenție suplimentară.

ICU MessageFormat

Dacă proiectul tău utilizează sintaxa ICU ({count, plural, one {1 item} other {# items}}), i18next o tratează ca interpolare, dar structura este mai complexă. Asigură-te că instrumentul tău de traducere recunoaște parametrii ICU și nu traduce numele categoriilor precum one, other sau identificatorii de format precum plural, number, date.

Componenta Trans cu noduri React

<Trans> randează componente React în interiorul șirurilor traduse, indexate (<0>, <1>). Traducătorul trebuie să păstreze ordinea exactă a tag-urilor. Blocarea sintaxei SimplePoTranslate gestionează acest lucru, dar dacă utilizezi un alt instrument, verifică înainte de a livra.

Fișiere Namespace

Aplicațiile mari împart localizările în namespace-uri: common.json, dashboard.json, checkout.json. Traduce fiecare fișier independent – nu le uni. Calitatea contextului este mai mare atunci când căile cheilor fiecărui namespace rămân delimitate.

Punerea tuturor cap la cap

Traducerea i18next JSON pentru o aplicație React sau Next.js nu înseamnă alegerea celui mai bun model AI. Este vorba despre respectarea regulilor structurale ale formatului: interpolările, sufixele de plural, cheile imbricate și tag-urile HTML trebuie să supraviețuiască ciclului complet. Instrumentele AI de uz general tratează JSON ca text nestructurat. Instrumentele conștiente de sintaxă îl analizează ca date structurate și ating doar suprafețele traductibile.

Dacă livrezi o aplicație multilingvă și ai copiat și lipit JSON în interfețe de chat, știi deja costul: ore de revizuire manuală per localitate, bug-uri aleatorii în producție și o stivă tot mai mare de forme de plural defecte. Un pipeline conștient de format elimină fiecare dintre aceste moduri de eșec.

Ești gata să traduci fișierele tale i18next JSON în siguranță? Încearcă SimplePoTranslate gratuit – nu este necesar un card de credit. Încarcă o singură dată, livrează în 41 de limbi.