Come Tradurre File JSON i18next in React & Next.js (2026)

Hai appena completato un'app React che deve essere distribuita in 12 lingue entro venerdì prossimo. I tuoi file locale si trovano in public/locales/en/common.json, hai 340 chiavi per locale, e i token all'interno delle tue stringhe assomigliano a {{userName}} e {{count}} sparsi in oggetti annidati. Incolli il JSON in ChatGPT, e ti restituisce {{ nombreUsuario }}, spazi extra e metà delle chiavi di pluralizzazione rinominate. La tua app va in crash durante il build.

Se hai provato ad automatizzare la traduzione JSON i18next, conosci questo problema. Il formato JSON è flessibile, ed è proprio per questo che la maggior parte degli strumenti di traduzione lo rovina. Il vero problema non è la qualità del modello linguistico, ma il fatto che gli strumenti AI di livello consumer non comprendono le regole strutturali di i18next.

Questa guida illustra cosa rende il JSON i18next diverso dagli altri formati locale, perché gli approcci di traduzione ingenui mandano in crash le app React e Next.js e come automatizzare la traduzione in modo sicuro su decine di locale senza dover revisionare manualmente ogni chiave.

Cos'è il JSON i18next e perché la traduzione è insidiosa

i18next è la libreria i18n più utilizzata nell'ecosistema JavaScript. Alimenta React (react-i18next), Next.js (next-i18next, App Router next-intl), Vue e i servizi di backend Node. Archivia le stringhe traducibili in file JSON piatti o annidati, uno per locale.

Un file tipico ha questo aspetto:

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

Questo sembra semplice, ma tre fattori lo rendono pericoloso da tradurre con un'IA generica.

I token di interpolazione sono strutturali, non testo

La sequenza {{userName}} non è una parola, è un segnaposto che il runtime sostituisce con i dati. Aggiungi uno spazio ({{ userName }}), rinominalo o traduci l'identificatore interno e il runtime fallirà silenziosamente o genererà un errore. Alcuni traduttori convertono utilmente {{count}} in {{conteo}} in spagnolo. La tua app ora tenta di interpolare una variabile che non esiste e rende il segnaposto grezzo al tuo utente.

Le chiavi di pluralizzazione sono suffissi magici

i18next rileva i plurali tramite suffissi: _zero, _one, _two, _few, _many, _other. Queste non sono stringhe arbitrarie, devono corrispondere alle categorie di plurale CLDR per la locale di destinazione. L'inglese usa solo _one e _other. Russo, arabo e polacco usano fino a sei categorie. Se il tuo traduttore elimina _other o lo rinomina, la catena di fallback si interrompe.

Le chiavi annidate devono rimanere intatte

A differenza dei file .po di Gettext, che sono coppie chiave-valore piatte, i file i18next possono annidarsi arbitrariamente. Un traduttore pigro potrebbe appiattire la struttura, cambiare i nomi delle chiavi per corrispondere al testo tradotto o riordinare gli oggetti. La tua chiamata t('cart.items_other') nel codice non si risolverà più.

Soluzioni sbagliate che gli sviluppatori provano per prime

Ogni team attraversa lo stesso ciclo di fallimento in tre fasi prima di investire in una soluzione reale.

Fase Uno: Incolla in ChatGPT

Copi 200 chiavi in ChatGPT, chiedi "traduci questo JSON in spagnolo" e incolli il risultato. Funziona per 180 chiavi. Venti hanno spazi aggiunti all'interno di {{...}}, tre hanno suffissi plurali riscritti e un tag <strong> è stato tradotto in <fuerte>. La tua build fallisce o invia silenziosamente stringhe difettose in produzione.

Fase Due: API di Google Translate

Colleghi l'API REST di Google Translate, iteri sul tuo JSON e invii ogni valore. La velocità è ottima. La qualità no. L'API di Google tratta ogni stringa in isolamento: nessun contesto sulla tua app, nessuna comprensione che {{count}} è un segnaposto, nessuna consapevolezza che la chiave cart.empty è diversa da cart.items_one. Hai comunque bisogno di una revisione umana per ogni chiave.

Fase Tre: Piattaforme TMS Commerciali

Ti iscrivi a un sistema di gestione delle traduzioni. Ti fanno pagare a parola, richiedono integrazioni GitHub e ti vincolano a posti mensili. Per un progetto secondario o un'app indipendente, l'economia crolla rapidamente – e ti imbatti comunque negli stessi problemi di corruzione dei segnaposto se il loro motore non analizza specificamente il formato i18next.

Gli stessi modi di fallimento si manifestano anche nei workflow Gettext. La nostra guida su come tradurre i file .po senza rompere le variabili del codice copre il problema parallelo per WordPress e altri stack basati su Gettext.

L'approccio sicuro: traduzione consapevole della sintassi

L'unico modo affidabile per tradurre il JSON i18next su larga scala è con uno strumento che analizza prima il formato, blocca la sintassi e invia solo il testo traducibile all'IA.

Ecco cosa fa l'elaborazione consapevole della sintassi sotto il cofano:

1. Analizza il JSON in un albero astratto, preservando i percorsi delle chiavi e l'annidamento.
2. Identifica i token di interpolazione ({{name}}, {{count, number}}, {{date, datetime}}) e li sostituisce con ID segnaposto.
3. Identifica i tag HTML all'interno dei componenti Trans (<0>, <strong>, <br/>) e li blocca.
4. Rileva le chiavi plurali tramite suffisso e le mappa alle regole CLDR per la locale di destinazione.
5. Invia solo il testo pulito all'LLM con il contesto relativo al percorso della chiave.
6. Reinserisce i token e i tag originali nelle loro posizioni esatte.
7. Convalida l'output: se un segnaposto è mancante o malformato, ripristina l'originale.

Questo è lo stesso principio che rende sicura la traduzione PO basata su cloud. Se sei curioso dell'architettura sottostante, la nostra comparazione della qualità della traduzione AI analizza come i diversi LLM gestiscono questi vincoli.

Passo dopo passo: Tradurre JSON i18next con SimplePoTranslate

SimplePoTranslate supporta i18next JSON nativamente nei piani Pro e Lifetime. Il livello gratuito attualmente copre .po e .pot - esegui l'upgrade o usa una prova per accedere al JSON.

1. Prepara il tuo file sorgente

Usa il tuo file inglese (o la locale sorgente) come master. Assicurati che sia un JSON valido e che contenga tutte le chiavi utilizzate dalla tua app. Un errore comune è lasciare chiavi obsolete o inutilizzate, il che consuma la tua quota di traduzione per stringhe che non renderizzerai mai.

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

2. Carica su SimplePoTranslate

Accedi alla tua dashboard, clicca su Nuova Traduzione e carica common.json. La piattaforma rileva automaticamente il formato i18next. Scegli la tua lingua di destinazione tra le 41 locale supportate, seleziona un tono (professionale, informale, marketing) e invia.

3. Lascia che il motore lavori

Sotto il cofano, il file viene analizzato, suddiviso in batch sicuri e tradotto in parallelo. I token di interpolazione sono bloccati. I suffissi plurali vengono preservati e mappati alle regole CLDR della locale di destinazione. L'HTML all'interno dei componenti Trans rimane intatto.

4. Scarica lo ZIP

Riceverai un ZIP contenente il JSON tradotto più formati alternativi (.php per app PHP, .po per compatibilità tra strumenti). Inserisci il JSON in public/locales/es/common.json e ridistribuisci.

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

5. Ripeti o elabora in batch

Per tutte le 12 locale di destinazione, invia 12 lavori. Le quote del piano Pro coprono decine di tipiche app SaaS. Per monorepo con più file namespace, carica ciascuno separatamente o elaborali in sequenza.

Integrazione delle traduzioni nella tua app

Una volta che hai tradotto i file JSON, l'integrazione è la parte facile. Alcuni accorgimenti:

• Verifica le categorie plurali. Esegui un rapido smoke test per locale: renderizza un componente con count={0}, count={1}, count={5} e conferma che tutti e tre producano la stringa corretta.
• Controlla le locale RTL. Se hai tradotto in arabo, ebraico o persiano, la tua UI necessita di CSS consapevole della direzione RTL. La nostra guida alla traduzione RTL per WordPress copre i pattern CSS che si applicano anche alle app React.
• Imposta una catena di fallback. Configura i18next in modo che ricada sull'inglese se una chiave è mancante, in modo che gli stati a metà deploy non facciano bloccare gli utenti.
• Blocca il tuo file sorgente in CI. Aggiungi un controllo che rifiuti le PR in cui en/common.json cambia senza rigenerare altre locale. La deriva della traduzione è la causa maggiore di bug i18n in produzione.

Per i team che distribuiscono su React, Next.js e lato server, produrre ogni formato da una singola sorgente è un enorme vantaggio. Il nostro post su un file in ingresso, cinque formati in uscita spiega perché l'output multi-formato è importante per la manutenzione a lungo termine.

Quando il JSON non basta: gestire casi complessi

Alcuni casi limite richiedono una cura extra.

Formato Messaggio ICU

Se il tuo progetto utilizza la sintassi ICU ({count, plural, one {1 item} other {# items}}), i18next la tratta come interpolazione ma la struttura è più complessa. Assicurati che il tuo strumento di traduzione riconosca i parametri ICU e non traduca i nomi delle categorie come one, other, o gli identificatori di formato come plural, number, date.

Componente Trans con Nodi React

Il <Trans> rende componenti React all'interno di stringhe tradotte, indicizzate (<0>, <1>). Il traduttore deve preservare l'ordine esatto dei tag. Il blocco della sintassi di SimplePoTranslate gestisce questo, ma se usi uno strumento diverso, verifica prima della distribuzione.

File Namespace

Le app grandi dividono le locale in namespace: common.json, dashboard.json, checkout.json. Traduci ogni file indipendentemente - non unirli. La qualità del contesto è maggiore quando i percorsi delle chiavi di ogni namespace rimangono delimitati.

Mettiamo tutto insieme

Tradurre il JSON i18next per un'app React o Next.js non riguarda la scelta del miglior modello AI. Riguarda il rispetto delle regole strutturali del formato: interpolazioni, suffissi plurali, chiavi annidate e tag HTML devono sopravvivere al ciclo di traduzione. Gli strumenti AI consumer trattano il JSON come testo non strutturato. Gli strumenti consapevoli della sintassi lo analizzano come dati strutturati e toccano solo le superfici traducibili.

Se stai distribuendo un'app multilingue e hai copiato-incollato JSON in interfacce di chat, conosci già il costo: ore di revisione manuale per locale, bug di produzione casuali e una crescente pila di forme plurali corrotte. Una pipeline consapevole del formato elimina ciascuna di queste modalità di fallimento.

Pronto a tradurre i tuoi file JSON i18next in modo sicuro? Prova SimplePoTranslate gratuitamente - nessuna carta di credito richiesta. Carica una volta, distribuisci in 41 lingue.