Blog

Chiavi di traduzione che rimangono coerenti in tutta un'app

Come localize.dev nomina le chiavi, le riutilizza per il testo ripetuto, separa i testi brevi e ambigui e nota quando il testo di origine cambia dopo essere stato tradotto.

Stephen Ufort · 6 novembre 2026 · 2 min di lettura

La pull request di Pages CMS: 535 stringhe in 73 file spostate su react-i18next, con chiavi e traduzioni

Le chiavi scritte a mano si discostano. Una persona scrive save_button, un'altra buttons.save, una terza common.actions.save, e tre chiavi contengono la stessa parola. Chiedere a un agente di codifica di estrarre stringhe un file alla volta si discosta allo stesso modo, perché ogni file inizia senza conoscere le chiavi che gli altri hanno creato.

localize.dev nomina le chiavi per l'intera app in un'unica esecuzione e le ricorda per la successiva. Questo post spiega come.

Chi nomina la chiave

Il modello propone ogni chiave dal percorso del file, dal componente e dalla stringa. Le regole che riceve sono brevi: segmenti in snake case minuscolo uniti da punti, uno spazio dei nomi per la funzionalità o lo schermo e un nome per ciò che fa la stringa, non una sua traslitterazione. src/components/AuthForm.tsx dà auth.*; un'intestazione diventa auth.welcome_heading, non auth.welcome_back_we_missed_you.

Tutto il resto è codice. Ogni chiave proposta viene pulita e registrata. Se due stringhe diverse ottengono lo stesso nome, la seconda ottiene un suffisso _2, e una chiave che entrerebbe in conflitto con un ramo esistente del file di localizzazione viene rinominata in modo che nessuna delle due sovrascriva l'altra.

Lo stesso testo ottiene la stessa chiave

Prima che una stringa venga inviata al modello, il motore controlla se quel testo ha già una chiave, sia nel file della lingua di origine sia da un punto precedente nella stessa esecuzione. In tal caso, il codice richiama nuovamente quella chiave e il modello non vede mai la stringa. Un'esecuzione segnala queste come chiavi riutilizzate, contando ogni luogo in cui appare il testo, quindi dieci pulsanti "Annulla" sono dieci riutilizzi di una chiave.

Testi brevi che significano due cose

Il riutilizzo basato solo sul testo è sbagliato per i testi brevi. "Pubblica" su un pulsante è un verbo, e nel titolo di una scheda è un sostantivo. Molte lingue usano parole diverse per ciascuno.

Una copia di tre parole o meno, fino a 40 caratteri, senza segnaposto o tag, ha senso accanto al suo testo: l’elemento e l’attributo in cui si trova, come button o input[placeholder]. "Posta" su un <button> e "Posta" in un <h3> diventano messaggi separati, e ciascuno viene inviato con un’indicazione di dove appare.

context sent with a string
"placeholder" attribute on <input> in component <Login>
element text inside <button> in component <Composer>

Quando le traduzioni dei due sensi tornano uguali in tutte le lingue, si fondono di nuovo in una chiave. Quando differiscono, entrambe le chiavi rimangono. Si ottiene una seconda chiave solo dove una lingua ne ha davvero bisogno.

Sapere quando il testo sorgente è cambiato

Le chiavi aiutano solo se le traduzioni rimangono aggiornate rispetto alla fonte. Quando qualcuno cambia "Salva" in "Salva modifiche" in en.json, tutte le traduzioni di quella chiave sono obsolete, ma il file non lo indica.

localize.lock.json registra l’impronta di ogni messaggio sorgente al momento della traduzione: i primi 12 caratteri esadecimali del suo SHA-256. Committalo con il tuo codice. Alla prossima esecuzione, un messaggio la cui impronta digitale non corrisponde più verrà tradotto di nuovo, e localize-dev check fallirà in CI con un errore "Traduzioni obsolete" che nomina le chiavi.

Chiavi in altri stack

Non tutti gli stack usano chiavi punteggiate. I file JSON di Laravel e i cataloghi gettext usano il testo sorgente come chiave, quindi anche localize.dev. Le chiavi ARB di Flutter sono camelCase e quelle di Android sono snake_case, perché è quello che aspettano i loro strumenti.

Provalo sul tuo codice nell'area di gioco, non è necessario un account