# General Translation Knowledge Base: Come assegnare i nomi alle chiavi di traduzione i18n? URL: https://generaltranslation.com/it/kb/i18n-key-naming.mdx Docs index: https://generaltranslation.com/llms.txt Description: 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. Category: Internazionalizzazione Last updated: 2026-10-20 Authors: Kevin Wu, Jackie Chen Published: 2026-10-20 Una chiave è l'identificatore che il codice usa per recuperare una traduzione, come in `t('summary.title', { ns: 'checkout' })`. Un buon nome resiste alle revisioni del testo, indica ai traduttori dove compare la stringa e rende facile individuare le chiavi inutilizzate. Le convenzioni seguenti valgono per i18next, react-i18next, Rails I18n, vue-i18n e qualsiasi altra libreria che legga file JSON o YAML basati su chiavi; gli esempi usano la sintassi di i18next e sono stati testati con i18next 26.5.3. ## 1. Namespace per funzionalità o schermata Inizia ogni chiave con l'area del prodotto a cui appartiene, poi il componente e infine l'elemento. * ✅ `checkout.summary.title`, `settings.billing.cancelButton` * ❌ `title1`, `text_47`, `newString` Quando il primo segmento corrisponde a un file separato, si tratta di un namespace e non di una parte del percorso della chiave. Se `summary.title` è memorizzata in `checkout.json`, i18next la trova con `t('summary.title', { ns: 'checkout' })` o `t('checkout:summary.title')`; `t('checkout.summary.title')`, invece, restituisce la stringa della chiave stessa, perché cerca un oggetto `checkout` nel namespace predefinito. Il prefisso indica al traduttore dove compare il testo e ti permette di suddividere i cataloghi in più file. i18next chiama questi file [namespace](https://www.i18next.com/principles/namespaces) e consiglia di suddividerli per vista, per funzionalità o per modulo caricato in modo lazy, oltre a prevedere un namespace `common` per etichette come Salva e Annulla. In React, react-i18next ne carica uno con `useTranslation('checkout')`, mentre l'[opzione `keyPrefix`](https://react.i18next.com/latest/usetranslation-hook) permette di abbreviare i percorsi annidati. ## 2. Descrivi il significato, non la formulazione Una chiave dovrebbe restare valida anche dopo che il marketing ha riscritto la frase. * ✅ `auth.login.submit` * ❌ `auth.login.clickHereToSignInNow` Se in seguito il pulsante diventa «Continua», la prima chiave resta corretta. La seconda, invece, descrive un testo che non esiste più: prima o poi qualcuno la rinominerà, rompendo ogni riferimento e lasciando orfane le traduzioni. ## 3. Una chiave per contesto, non una per stringa inglese Due stringhe identiche in inglese spesso hanno traduzioni diverse. "Open" su un pulsante è un verbo; "Open" come stato di un ticket è un aggettivo. In tedesco si usa *Öffnen* nel primo caso e *Offen* nel secondo. * ✅ `files.actions.open` e `tickets.status.open` * ❌ un unico `common.open` riutilizzato per entrambi Riserva il namespace condiviso `common` alle etichette che hanno lo stesso significato ovunque, come il pulsante Annulla. I sistemi basati sul testo sorgente risolvono lo stesso problema tramite il contesto: [`msgctxt`](https://www.gnu.org/software/gettext/manual/html_node/Contexts.html) di GNU gettext consente di associare due traduzioni a una stessa stringa inglese. ## 4. Scegli tra JSON annidato o piatto, senza mescolarli In `checkout.json`, i18next interpreta `summary.title` come un percorso, perché il valore predefinito del suo `keySeparator` è `.`. Entrambe le strutture funzionano: scegline una, così che file, revisori e strumenti siano tutti allineati. ```json title="locales/en/checkout.json (nested)" { "summary": { "title": "Order summary", "taxNotice": "Tax is calculated at checkout." } } ``` ```json title="locales/en/checkout.json (flat)" { "summary.title": "Order summary", "summary.taxNotice": "Tax is calculated at checkout." } ``` Per i file piatti, la [documentazione sulla configurazione](https://www.i18next.com/overview/configuration-options) di i18next consiglia di impostare `keySeparator` su `false`. Scegli anche una convenzione per maiuscole e minuscole (segmenti in `camelCase` o `snake_case`) e applicala in tutti i file. ## 5. Usa i suffissi di plurale e di contesto della tua libreria i18next seleziona le forme plurali in base al suffisso e richiede che la variabile si chiami `count`. Una voce `_zero` sovrascrive la regola della lingua quando il conteggio è 0, mentre gli ordinali aggiungono `_ordinal`: ```json title="locales/en/checkout.json" { "cart": { "itemCount_zero": "Your cart is empty", "itemCount_one": "{{count}} item", "itemCount_other": "{{count}} items" } } ``` `t('cart.itemCount', { count: 0 })` restituisce "Il tuo carrello è vuoto", con 1 restituisce "1 articolo" e con 5 restituisce "5 articoli". Una lingua con più categorie di plurale aggiunge chiavi come `itemCount_few` e `itemCount_many`. (Consulta la [documentazione di i18next sui plurali](https://www.i18next.com/translation-function/plurals) e [Che cos'è l'ICU formato dei messaggi?](/kb/icu-message-format) per le categorie di ciascuna lingua.) * ✅ `itemCount_one`, `itemCount_other` e, per i testi che variano in base al genere, chiavi di [contesto](https://www.i18next.com/translation-function/context) come `friend_male` e `friend_female` * ❌ suffissi inventati come `itemCount_singular` e `itemCount_plural`, che la libreria non selezionerà mai Le librerie basate sull'ICU formato dei messaggi (react-intl, next-intl, Lingui), invece, raccolgono tutte le forme plurali in un unico messaggio associato a un'unica chiave. ## 6. Non comporre mai una frase con più chiavi L'ordine delle parole cambia da una lingua all'altra, quindi una frase suddivisa su più chiavi non può essere tradotta correttamente. * ❌ `t('account.hello') + name + t('account.welcomeBack')` * ✅ una sola chiave con un segnaposto: `"account.welcome": "Hello, {{name}}! Welcome back."` Se un messaggio contiene un conteggio, mantieni la frase completa anche in ogni forma plurale, usando i suffissi della convenzione 5. Il [manuale di GNU gettext](https://www.gnu.org/software/gettext/manual/html_node/Preparing-Strings.html) stabilisce la stessa regola per i propri cataloghi: tradurre frasi intere e usare stringhe di formato anziché la concatenazione. ## 7. Scegliere tra chiavi stabili e testo di origine come chiave Non tutti i sistemi si basano su nomi inventati. La vera scelta è chi gestisce l'identificatore: | Approccio | Esempio | Punto di forza | Costo | | --------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Chiavi semantiche (i18next, Rails I18n) | `t('summary.title', { ns: 'checkout' })` | Le modifiche ai testi non toccano il codice; le chiavi indicano dove si trova il testo | Qualcuno deve assegnare un nome a ogni chiave, archiviarla e rimuoverla quando non serve più | | Testo di origine come chiave (gettext) | `_("Order summary")` | Il codice resta leggibile; non serve scegliere nomi | Una modifica al testo inglese crea una nuova voce; i conflitti tra testi identici richiedono `msgctxt` | | ID generati dal testo inline (FormatJS) | `defaultMessage="Order summary"` | Il messaggio sta accanto al punto in cui viene usato; gli ID sono automatici | Richiede un plugin di build e una fase di estrazione | Usa le chiavi semantiche quando i testi sono gestiti al di fuori della base di codice (ad esempio, da un team di contenuti che modifica le stringhe in un TMS) o quando le app web e mobile condividono un unico catalogo. Usa il testo di origine o i messaggi inline quando sono gli sviluppatori a scrivere i testi e vuoi che la code review mostri esattamente le parole che vedranno gli utenti. ## 8. Tieni le chiavi fuori da URL, analytics e logica Le chiavi e le stringhe tradotte servono solo alla visualizzazione. Non inviare `t('checkout:cta')` come nome di un evento di analytics (ogni impostazione regionale registrerebbe un evento diverso), non costruire lo slug di una route a partire da una chiave e non basare una condizione su `label === t('status.open')`. Usa invece un nome di evento fisso, uno slug che controlli tu e un enum o un codice di stato. Così, rinominare una chiave o modificare una traduzione non potrà mai rompere una dashboard, un link o una condizione. ## 9. Ripulisci automaticamente le chiavi inutilizzate e mancanti I cataloghi tendono a disallinearsi: le chiavi restano anche dopo l'eliminazione del relativo componente, e le nuove chiavi finiscono in produzione senza traduzione. Esegui un controllo nella CI. * **i18next**: [`i18next-cli`](https://github.com/i18next/i18next-cli) sostituisce `i18next-parser`, ormai deprecato. In un piccolo progetto di prova, `npx i18next-cli status --unused` ha segnalato una chiave orfana `oldPromoBanner` senza modificare alcun file; `npx i18next-cli extract` l'ha poi rimossa (la sua opzione `removeUnusedKeys` è impostata su `true` per impostazione predefinita) e ha scritto voci tedesche vuote per ogni chiave, incluse `itemCount_one` e `itemCount_other`. `npx i18next-cli status` termina con un errore finché mancano delle traduzioni, mentre `rename-key` rinomina una chiave sia nei file sorgente sia in quelli delle impostazioni regionali. L'analisi statica non è in grado di rilevare le chiavi costruite a runtime, come ``t(`status.${code}`)``, quindi `extract` le considera inutilizzate e le elimina. Elenca questi prefissi nell'opzione `preservePatterns` (ad esempio, `'status.*'`) oppure scrivi ogni chiave per esteso nel codice. * **Rails**: i18n-tasks segnala le chiavi mancanti e inutilizzate nel codice Ruby ed ERB. (Vedi [General Translation vs. i18n-tasks](/kb/general-translation-vs-i18n-tasks).) ## Come General Translation gestisce le chiavi Con il componente [``](/docs/react/reference/components/t) di `gt-react` o `gt-next`, il testo in inglese resta all'interno del componente e non c'è nessuna chiave da nominare: ```tsx title="CheckoutSummary.tsx" import { T } from 'gt-react'; export function CheckoutSummary() { return (

Order summary

Tax is calculated at checkout. ); } ``` [`npx gt translate`](/docs/cli/reference/commands/translate) estrae il contenuto ancora presente nel codice sorgente, quindi rimuovendo un componente non c'è più bisogno di gestirne manualmente le chiavi. Gli usi distinti di "Open" richiedono comunque un contesto: `Open` oppure `gt('Open', { $context: 'Ticket status' })` con [`useGT`](/docs/react/reference/hooks/use-gt). Una prop facoltativa [`id`](/docs/react/reference/components/t#id) su [``](/docs/react/reference/components/t), o un'opzione `$id` nella funzione di traduzione, assegna a una voce un identificatore stabile per l'editor di traduzione. (Vedi [Posso fare i18n senza file di traduzione?](/kb/i18n-without-translation-files).) I team che preferiscono le chiavi possono continuare a usarle. Scrivi un unico dizionario sorgente, come `dictionary.json`, e leggilo con [`useTranslations`](/docs/react/reference/hooks/use-translations); lo stesso comando lo traduce e, se si cerca un id non presente nel dizionario, viene sollevata un'eccezione anziché renderizzare una chiave grezza. (Vedi [Tradurre con i dizionari](/docs/react/guides/translating-with-dictionaries).) I file JSON esistenti di i18next o next-intl vengono tradotti così come sono, e un [file `.metadata.json`](/docs/cli/reference/keyed-metadata) associato aggiunge contesto o un limite di caratteri per singola chiave: l'equivalente della convenzione 3 per l'approccio basato su chiavi. ## Punti chiave * Assegna un nome alle chiavi in base alla posizione nell'interfaccia e al significato (`checkout.summary.title`), mai in base al testo o all'ordine (`text_47`). * Usa chiavi separate per "Open" come verbo e "Open" come stato; condividi una chiave solo quando il significato è identico. * Rispetta esattamente i suffissi per i plurali previsti dalla libreria: i18next usa `_one`, `_other` e `_zero`, mentre le librerie ICU gestiscono i plurali in un unico messaggio. * Esegui `i18next-cli status --unused` o i18n-tasks nella CI per evitare che si accumulino chiavi inutilizzate o mancanti. * Il componente [``](/docs/react/reference/components/t) di General Translation non richiede chiavi, mentre la sua modalità dizionario con [`useTranslations`](/docs/react/reference/hooks/use-translations) le conserva per i team che preferiscono usarle. ## Related questions - [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. - [General Translation vs. i18n-tasks: quale scegliere?](https://generaltranslation.com/it/kb/general-translation-vs-i18n-tasks.mdx): i18n-tasks è una gem Ruby che individua le chiavi Rails I18n mancanti e inutilizzate, riordina i file delle impostazioni regionali e può compilare le chiavi mancanti tramite Google Translate, DeepL, OpenAI, Yandex o watsonx. General Translation traduce interi file delle impostazioni regionali con il tuo Glossario, i prompt personalizzati e la revisione nella dashboard. Svolgono compiti diversi e molti team possono usarli entrambi. - [Alternative a i18next: General Translation vs. i18next](https://generaltranslation.com/it/kb/general-translation-vs-i18next.mdx): Scegli General Translation per mantenere i testi inline nei componenti React e generare le traduzioni sfruttando la struttura JSX e il contesto del prodotto. In alternativa, puoi continuare a usare i18next e affidarti a General Translation per tradurre i cataloghi esistenti. i18next si occupa del rendering dei messaggi e della selezione dei plurali, mentre la generazione delle traduzioni è affidata a un servizio separato. - [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 si trovano le stringhe hardcoded non tradotte?](https://generaltranslation.com/it/kb/find-hardcoded-strings.mdx): Esegui in CI un linter che segnali i letterali stringa visibili all'utente, come la regola no-literal-string di eslint-plugin-i18next per JSX, il controllo HardcodedText di Android Lint o il linter HardCodedString di erb_lint per Rails. Poi naviga nell'app con una pseudo-impostazione regionale per individuare il testo che i controlli statici non riescono a tracciare. ## Previous and next questions - Previous question: [Che cos'è un sistema di gestione delle traduzioni (TMS)?](https://generaltranslation.com/it/kb/what-is-a-translation-management-system.mdx) - Next question: [Come si localizza un'app iOS con gli String Catalog?](https://generaltranslation.com/it/kb/localize-ios-app.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.