# General Translation Knowledge Base: Come si traducono i file JSON di i18n? URL: https://generaltranslation.com/it/kb/translate-json-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Traduci solo i valori stringa di un file JSON di impostazione regionale. Lascia invariati le chiavi non plurali, i segnaposto come {{name}} e i tag, ma tieni presente che le chiavi plurali cambiano da una lingua all'altra: il polacco, ad esempio, richiede inbox_few e inbox_many. Usa uno strumento o un'API in grado di gestire il formato, quindi esegui il parsing dell'output e validalo prima della revisione. Category: Traduzione Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Questa risposta riguarda i file di impostazione regionale caricati da librerie i18n come i18next, react-intl, next-intl e vue-i18n, in cui ogni chiave corrisponde a una stringa della UI. I file JSON con dati arbitrari (risposte API, cataloghi di prodotti) richiedono un approccio diverso, perché in quel caso devi decidere campo per campo cosa tradurre. ## Come sono fatti i file JSON delle impostazioni regionali La maggior parte dei file delle impostazioni regionali ha una struttura annidata, in cui le chiavi sono raggruppate in oggetti, come nell'esempio seguente. Un file piatto, invece, esprime lo stesso percorso con un'unica chiave in notazione puntata, ad esempio `"nav.home": "Home"`. ```json title="locales/en/common.json" { "nav": { "home": "Home", "save": "Save" }, "greeting": "Hello, {{name}}!", "inbox_one": "You have {{count}} new message", "inbox_other": "You have {{count}} new messages", "terms": "Read our <1>terms before you continue." } ``` La sintassi delle stringhe al loro interno dipende dalla libreria, e una traduzione deve lasciarla intatta: * **i18next** interpola con doppie parentesi graffe (`{{name}}`) e memorizza i plurali come chiavi separate con [suffissi](https://www.i18next.com/translation-function/plurals) come `_one`, `_few`, `_many` e `_other`, secondo le regole del plurale di ciascuna lingua. Il componente `` di react-i18next aggiunge tag numerati come `<1>terms`. * **react-intl e next-intl** memorizzano messaggi ICU, in cui i segnaposto usano parentesi graffe singole e i plurali sono definiti all'interno della stringa: `{count, plural, one {# message} other {# messages}}`. (Vedi [Che cos'è l'ICU formato dei messaggi?](/kb/icu-message-format)). * **vue-i18n** usa segnaposto con parentesi graffe singole e separa le forme plurali con una barra verticale: `no apples | one apple | {count} apples` ([pluralizzazione in vue-i18n](https://vue-i18n.intlify.dev/guide/essentials/pluralization)). Anche il modo in cui vengono denominate le chiavi è importante, perché spesso un traduttore vede soltanto la chiave e il valore. (Vedi [Come dovrei denominare le chiavi di traduzione i18n?](/kb/i18n-key-naming)). ## Cosa va storto quando si incolla un JSON in un traduttore Un traduttore generico tratta il file come semplice testo, mettendone a rischio la struttura: * **Le chiavi vengono tradotte.** `"nav"` diventa `"nawigacja"` e l'app non trova più la stringa. * **I segnaposto cambiano.** `{{name}}` diventa `{{nombre}}`, oppure sparisce una parentesi graffa, e l'interpolazione fallisce a runtime. * **I tag si rompono.** `<1>terms` viene tradotto, rinumerato o eliminato, e il link non racchiude più le parole giuste. * **Il file non è più un JSON valido.** Virgolette tipografiche, un `"` non escapato all'interno di una stringa tradotta o una virgola finale bastano a far fallire il parsing dell'intero file. * **Mancano le chiavi plurali.** Traducendo `inbox_one` e `inbox_other` chiave per chiave, il polacco resta senza le chiavi `inbox_few` e `inbox_many` richieste da i18next, e "5 messaggi" non ha una forma polacca corretta da mostrare. (Consulta [Cos'è l'ICU formato dei messaggi?](/kb/icu-message-format) per le categorie di plurale di ciascuna lingua.) * **Le stringhe brevi perdono il loro significato.** In tedesco, `"save": "Save"` può essere *speichern* (salvare un file) o *sparen* (risparmiare), e la sola chiave raramente chiarisce quale dei due. ## Modi per tradurre i file JSON delle impostazioni regionali | Approccio | Chiavi e segnaposto | Forme plurali | Contesto per stringhe brevi | Gestione delle modifiche | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | A mano, o tramite un traduttore che lavora direttamente sul file | Sicuro se chi traduce è attento | Le aggiunge chi traduce, se conosce le regole | Chi traduce può chiedere | Manuale per ogni modifica | | Traduttore JSON online (carichi un file, scarichi una traduzione) | Dipende dallo strumento; prova prima con un file ricco di segnaposto | Dipende dallo strumento | Dipende dallo strumento | Ricarica il file a ogni modifica | | Script basato sull'API di DeepL o Google Cloud Translation | Scorri il JSON e invii solo i valori; l'API per documenti di DeepL accetta anche `.json` e protegge i segnaposto per impostazione predefinita | Generi tu le chiavi mancanti | Il parametro `context` di DeepL; Google non offre nulla per singola stringa | Riesegui lo script e confronti l'output con un diff | | Prompt a un LLM con il file | Di solito vengono mantenuti, ma nulla lo garantisce | Aggiunte se lo chiedi e indichi le categorie | Tutto ciò che inserisci nel prompt | Riesegui il prompt e convalidi ogni esecuzione | | CLI di General Translation | Legge la struttura JSON e traduce i valori | Traduce le voci esistenti; verifica le famiglie plurali della lingua di destinazione | Note e limiti di lunghezza per chiave, Glossario e prompt personalizzati condivisi | Riutilizza le traduzioni corrispondenti; genera gli aggiornamenti prima della build | | Sistema di gestione delle traduzioni (TMS) | Analisi in base al formato, quindi le chiavi sono al sicuro | Dipende dal TMS e dal formato del file | Screenshot, commenti e descrizioni per chiave | Sincronizza i file tramite l'integrazione con il repository del TMS | Due delle opzioni basate su script meritano qualche dettaglio in più. L'[API per documenti](https://developers.deepl.com/api-reference/document) di DeepL elenca `json` tra i formati supportati e, per impostazione predefinita, mantiene invariati segnaposto come `{stars}` o `{{userName}}` e protegge gli skeleton plurali ICU, traducendo solo il testo dei rami. La [traduzione di documenti](https://docs.cloud.google.com/translate/docs/advanced/translate-documents) di Google accetta file Office e PDF ma non JSON, e il sito consumer di Google Traduttore accetta solo file `.docx`, `.pdf`, `.pptx` e `.xlsx`: con Google, quindi, devi estrarre tu i valori delle stringhe e inviarli all'API di testo. Usa un'attenta revisione manuale o l'API per documenti di DeepL quando devi tradurre una sola volta un file di piccole dimensioni. Usa uno script o un prompt a un LLM se sei disposto a occuparti in prima persona della convalida e delle riesecuzioni. Usa General Translation se vuoi che i cataloghi generati e revisionati vengano rilasciati insieme alle modifiche al codice, continuando a usare la tua libreria di rendering. Usa un [sistema di gestione delle traduzioni](/kb/what-is-a-translation-management-system) quando un team di traduttori lavora al di fuori della base di codice. ## Come tradurre i file JSON con General Translation Se i file si trovano nel tuo repository e cambiano a ogni rilascio, puoi mantenerli aggiornati con un comando nella tua build. La CLI di General Translation, `gt`, traduce i file JSON delle impostazioni regionali, inclusi i cataloghi basati su i18next e ICU, e ti permette di continuare a usare la libreria che li renderizza. Installa la CLI con `npm install gt --save-dev`, esegui [`npx gt init`](/docs/cli/reference/commands/init) per creare `gt.config.json` ed effettuare l'accesso, quindi fai puntare `files.json.include` ai tuoi file sorgente. Il segnaposto `[locale]` indica alla CLI da dove leggere il locale di origine e dove scrivere ciascuna impostazione regionale di destinazione: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["de"], "files": { "json": { "include": ["locales/[locale]/*.json"] } } } ``` Per un progetto esistente, esegui prima [`npx gt upload`](/docs/cli/reference/commands/upload) per importare i contenuti sorgente e le traduzioni già revisionate. [`npx gt translate`](/docs/cli/reference/commands/translate) legge quindi tutti i file in `locales/en/` e scrive i file in tedesco in `locales/de/`, pronti per la revisione e il commit; aggiungi `--dry-run` per elencare i file trovati senza chiamare l'API. Questo esempio usa inglese e tedesco, i cui messaggi cardinali usano entrambi le categorie `one` e `other` mostrate sopra. Nelle esecuzioni successive, le traduzioni corrispondenti possono essere riutilizzate. Se il tuo `package.json` dichiara `i18next` o `next-intl`, la CLI mantiene la sintassi delle stringhe di quella libreria, inclusi i messaggi ICU. (Consulta il [riferimento sul formato JSON](/docs/cli/reference/formats/json-files).) Per disambiguare una stringa breve come "Save", aggiungi un file associato `common.metadata.json` con le stesse chiavi e, per ciascuna stringa, una nota `context` o un limite `maxChars`. (Consulta [Metadati associati alle chiavi](/docs/cli/reference/keyed-metadata).) Per `nav.save`, usa una nota come «Salva su disco il documento modificato», così il servizio non deve basarsi solo su un'etichetta ambigua. Si applicano anche i termini del Glossario e i prompt personalizzati definiti nei gruppi di contesto del tuo progetto. Revisiona i testi generati nell'[editor della dashboard](/docs/platform/dashboard/guides/reviewing-translations); se i revisori modificano i file scaricati, usa [`npx gt save-local`](/docs/cli/reference/commands/save-local). I controlli descritti di seguito verificano la struttura dei messaggi, indipendentemente dalla revisione linguistica. ## Controlla i file tradotti prima del rilascio Valida l'output con lo stesso formato dei messaggi e le stesse regole dell'impostazione regionale utilizzati dalla tua applicazione: * **Analizza il JSON e confronta le chiavi non plurali.** Controlla sia le chiavi di primo livello sia i percorsi delle chiavi annidate. Chiavi mancanti o rinominate possono far fallire le ricerche anche quando il parsing del JSON va a buon fine. Gestisci gli array e i valori non stringa in base allo schema della tua applicazione. * **Controlla i plurali di i18next come famiglie plurali.** Raggruppa le chiavi come `inbox_one` e `inbox_other` in base alla chiave di base, quindi verifica le categorie dell'impostazione regionale di destinazione. Il polacco richiede anche `inbox_few` e `inbox_many`: si tratta di aggiunte obbligatorie, non di chiavi inattese. Il giapponese può usare solo `inbox_other`. i18next segue `Intl.PluralRules` e consente anche una forma speciale `_zero`; usa le regole appropriate per i messaggi cardinali o ordinali. (Consulta le [regole del plurale di i18next](https://www.i18next.com/translation-function/plurals).) * **Mantieni segnaposto e tag in ogni forma tradotta.** Controlla anche le forme plurali appena aggiunte. `{{name}}` deve continuare a riferirsi a `name` e i tag numerati devono continuare a identificare i componenti previsti, anche se il loro ordine cambia. * **Analizza i messaggi ICU e confrontane gli argomenti.** Usa un parser come il [parser di messaggi ICU di FormatJS](https://formatjs.github.io/docs/icu-messageformat-parser/) anziché un'espressione regolare per le parentesi graffe annidate. Il solo parsing non basta: rinominare l'argomento plurale da `count` a `total` produce una sintassi valida, ma non corrisponde più al valore fornito dall'applicazione. Controlla nomi e tipi degli argomenti, tag rich text, casi di select, selettori di numeri esatti come `=0` e offset dei plurali. Ammetti categorie di plurale specifiche del locale: il ramo `other`, obbligatorio in ICU, funge da fallback, quindi i messaggi ICU non devono necessariamente contenere ogni categoria CLDR. Le chiavi plurali mancanti non generano errori evidenti. Questo file polacco contiene tutte e quattro le categorie, mentre una traduzione chiave per chiave si sarebbe fermata a `inbox_one` e `inbox_other`: ```json title="locales/pl/common.json" { "inbox_one": "Masz {{count}} nową wiadomość", "inbox_few": "Masz {{count}} nowe wiadomości", "inbox_many": "Masz {{count}} nowych wiadomości", "inbox_other": "Masz {{count}} nowej wiadomości" } ``` Se caricato con i18next 26.5.3 e `fallbackLng: 'en'`, il file tradotto chiave per chiave ripiega sull'inglese per ogni conteggio che richiede `few` o `many`, anziché sulla forma polacca `other`: ```text title="Output" count category key-by-key file complete file 1 one Masz 1 nową wiadomość Masz 1 nową wiadomość 2 few You have 2 new messages Masz 2 nowe wiadomości 5 many You have 5 new messages Masz 5 nowych wiadomości 22 few You have 22 new messages Masz 22 nowe wiadomości 1.5 other Masz 1.5 nowej wiadomości Masz 1.5 nowej wiadomości ``` Il decimale viene visualizzato come `1.5` perché il valore non è formattato come numero; se possono comparire valori frazionari, formattalo in base all'impostazione regionale. Infine, carica i messaggi tramite la libreria i18n della tua applicazione e verificali nel loro contesto. Prova quantità che attivino ciascuna forma plurale, inclusi lo zero e i decimali, se pertinenti. I controlli di sintassi non possono stabilire se una traduzione è accurata né se il testo si adatta all'interfaccia. Le regole di interpolazione personalizzate e la sintassi con barra verticale di vue-i18n richiedono controlli specifici per quei formati. ## Punti chiave * Traduci i valori mantenendo intatta la sintassi dei messaggi. Le chiavi non plurali restano invariate, mentre quelle plurali possono variare da lingua a lingua. * Le categorie di plurale variano da lingua a lingua: il polacco richiede le chiavi `_few` e `_many`, assenti in una sorgente inglese. * L'API per documenti di DeepL accetta JSON e protegge i segnaposto per impostazione predefinita; la traduzione di documenti di Google, invece, non accetta JSON. * Per tradurli con la CLI `gt`, imposta `files.json.include` su un pattern contenente `[locale]` ed esegui [`npx gt translate`](/docs/cli/reference/commands/translate); i metadati associati alle chiavi consentono di aggiungere contesto e limiti di lunghezza a ogni singola stringa. * Valida le famiglie plurali di i18next in base all'impostazione regionale di destinazione ed esegui il parsing dei messaggi ICU anziché verificarne la sintassi annidata con un'espressione regolare. ## Related questions - [Che cos'è l'ICU formato dei messaggi?](https://generaltranslation.com/it/kb/icu-message-format.mdx): L'ICU formato dei messaggi è una sintassi che permette a una singola stringa traducibile di contenere variabili, plurali, scelte select e ordinali, come {count, plural, one {# file} other {# files}}. Ogni lingua usa le categorie di plurale CLDR di cui ha bisogno: l'inglese usa one e other, mentre il polacco aggiunge few e many. - [Come assegnare i nomi alle chiavi di traduzione i18n?](https://generaltranslation.com/it/kb/i18n-key-naming.mdx): Assegna i nomi alle chiavi in base a dove compare il testo e a cosa significa, ad esempio checkout.summary.title, e non in base alla formulazione inglese. Dai a ogni uso distinto una chiave propria, anche quando il testo inglese è identico: in tedesco il pulsante Open diventa Öffnen, mentre lo stato Open diventa Offen. - [General Translation vs. i18next, react-intl e next-intl: quale libreria i18n scegliere?](https://generaltranslation.com/it/kb/general-translation-vs-i18n-libraries.mdx): Le librerie open source come i18next, react-intl e next-intl non traducono nulla. Si limitano a visualizzare le traduzioni che fornisci in un file di catalogo per ciascuna lingua, scritte da te, dai tuoi traduttori o da un servizio esterno. Anche le librerie di General Translation sono open source e svolgono lo stesso compito, ma General Translation si occupa anche della traduzione, usando il tuo codice come contesto. - [Posso fare i18n senza file di traduzione?](https://generaltranslation.com/it/kb/i18n-without-translation-files.mdx): Sì. Le librerie gt-react e gt-next di General Translation gestiscono l'i18n in React e Next.js senza chiavi di traduzione e senza dover mantenere un file JSON per ogni lingua. I testi restano inline nel JSX all'interno del componente `` e il comando gt translate genera le traduzioni per ogni lingua durante la build, sfruttando il contesto del tuo codice. Locadex può mantenerle aggiornate tramite pull request. - [La traduzione con l'IA è abbastanza accurata per un'app in produzione?](https://generaltranslation.com/it/kb/is-ai-translation-accurate.mdx): Spesso sì, per le lingue più diffuse, ma solo dopo aver superato una valutazione sulle tue lingue, sulle tue stringhe di UI e sui contenuti più a rischio. Al WMT25, Gemini 2.5 Pro ha eguagliato o superato le traduzioni umane di riferimento in 10 coppie linguistiche su 16, ma un benchmark sui documenti non dice se brevi stringhe di interfaccia siano pronte per il rilascio. ## Previous and next questions - Previous question: [Come si supportano le lingue RTL (right-to-left) in CSS?](https://generaltranslation.com/it/kb/right-to-left-css.mdx) - Next question: [Come si traducono i sottotitoli SRT senza alterare la temporizzazione?](https://generaltranslation.com/it/kb/translate-srt-subtitles.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.