# General Translation Knowledge Base: Come si traducono i file di impostazioni regionali YAML? URL: https://generaltranslation.com/it/kb/translate-yaml-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Traduci solo i valori delle stringhe e lascia invariati chiavi, segnaposto come %{name} o {{name}} e ancore. Racchiudi tra virgolette i valori che contengono i due punti o che iniziano con % o {, imposta in ogni file la radice dell'impostazione regionale o il nome del file e aggiungi le chiavi plurali richieste dalla lingua di destinazione. La CLI di General Translation traduce i valori YAML in-place senza toccare le chiavi. Category: Traduzione Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 Un file di impostazioni regionali YAML associa chiavi a stringhe visibili all'utente, con un file (o una chiave di primo livello) per ogni lingua. Tradurlo significa sostituire i valori delle stringhe lasciando chiavi, segnaposto e struttura del file esattamente come se li aspetta il framework. Rispetto a JSON, YAML complica le cose: dei due punti senza virgolette o un `%` iniziale mandano in errore il parsing, e `no` può essere interpretato come booleano. Così, anche una traduzione corretta può generare un file che la tua app rifiuta o interpreta in modo errato. ## Layout comuni delle impostazioni regionali in YAML Ogni framework colloca la lingua in una posizione diversa e adotta una propria sintassi per i segnaposto; un file tradotto deve rispettare le stesse regole: | Framework | File sorgente | Posizione della lingua | Segnaposto | Plurali | | -------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------ | ---------------------------------------------- | --------------------------------------------------------- | | [Rails I18n](https://guides.rubyonrails.org/i18n.html) | `config/locales/en.yml` | Chiave di primo livello (`en:`) | `%{name}` | Chiavi `one` e `other`; altre con rails-i18n | | [Symfony](https://symfony.com/doc/current/translation.html#translation-resource-file-names-and-locations) | `translations/messages.en.yaml` | Nome del file (`domain.locale.yaml`) | `%name%`, oppure `{name}` nei file `+intl-icu` | Plurali ICU all'interno della stringa | | [Hugo](https://gohugo.io/functions/lang/translate/#translation-tables) | `i18n/en.yaml` | Nome del file | Template Go come `{{ . }}` | Chiavi CLDR (`one`, `few`, `many`, `other`) | | i18next con [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend) | `locales/en/common.yml` | Directory | `{{name}}` | Chiavi con suffisso, come `_one` e `_other` | | vue-i18n con [unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) | `locales/en.yaml` | Nome del file | `{name}` | Forme separate da barre verticali in un'unica stringa | Rails è il più rigido in fatto di struttura. Secondo la [guida di Rails](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale), vengono caricati tutti i file `.yml` e `.rb` presenti in `config/locales` e in ciascun file "la chiave di primo livello è l'impostazione regionale". Un file in spagnolo deve quindi iniziare con `es:`, indipendentemente dal nome del file. ## Insidie YAML che compromettono i file tradotti Ecco un file Rails scritto in modo che ogni valore resti intatto dopo la traduzione: ```yaml title="config/locales/en.yml" en: checkout: title: "Note: prices include VAT" joined: "%{name} joined your team" confirm_no: "No" terms: | By paying, you agree to our terms. Refunds take 5 to 7 days. items: one: "%{count} item" other: "%{count} items" ``` Ogni riga protegge da un errore comune: * **Due punti.** `title: Note: prices include VAT` senza virgolette è un errore di sintassi, e una traduzione può introdurre dei due punti assenti nel testo inglese. * **Valori che iniziano con un carattere indicatore.** Un valore semplice non può iniziare con `%`, `{`, `[`, `@` o un backtick. `joined: %{name} joined your team` genera un errore di parsing, e `{{name}} joined` viene interpretato come l'inizio di una mappatura. Nella traduzione l'ordine delle parole cambia, quindi un segnaposto che in inglese stava a metà frase finisce spesso all'inizio. È per questo che la documentazione stessa di Hugo racchiude tra virgolette `'{{ . }} day'`. * **Booleani.** Il parser YAML di Ruby segue YAML 1.1, quindi `yes`, `no`, `on` e `off` senza virgolette diventano `true` e `false`; i parser YAML 1.2, inclusa la maggior parte degli strumenti JavaScript, li leggono invece come stringhe. La guida di Rails specifica che [queste chiavi devono essere sottoposte a escape](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale), e lo stesso vale per i valori. Persino un file norvegese con radice `no:` viene caricato in Ruby sotto la chiave `false`. * **Scalari a blocco.** `|` conserva le interruzioni di riga, mentre `>` le converte in spazi. Le righe tradotte devono mantenere l'indentazione del blocco, altrimenti il valore si interrompe prima del previsto o il parsing del file fallisce. * **Ancore e alias.** `&name` definisce un blocco e `*name` lo riutilizza, quindi modificando un valore ancorato si modificano tutti i relativi alias. Rails li carica, ma unplugin-vue-i18n dichiara che le sue risorse YAML [non supportano gli alias](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n): verifica quindi il comportamento del tuo loader prima di farci affidamento. Con le righe `title` e `joined` senza virgolette, ciascuna in un file separato, il parser di Ruby (Ruby 2.6, Psych 3.1) le rifiuta entrambe prima ancora che Rails legga una sola chiave: ```text title="Output" unquoted-colon.yml: mapping values are not allowed in this context at line 3 column 16 unquoted-placeholder.yml: found character that cannot start any token while scanning for the next token at line 3 column 13 ``` La regola più semplice è mettere tra virgolette ogni valore: una stringa tra virgolette doppie è sempre una stringa, quindi `%{name}`, i due punti e `No` restano testo. ### Le chiavi plurali variano da lingua a lingua L'inglese usa `one` e `other`, ma il russo e il polacco richiedono anche `few` e `many`. Le chiavi mancanti non generano alcun errore. Con il backend di pluralizzazione della gem i18n e una regola del plurale russa come quella inclusa in rails-i18n, un file tradotto chiave per chiave dall'inglese ricade silenziosamente su `other` per ogni quantità che richiederebbe `few`. Entrambi i file russi riportati di seguito contengono le traduzioni di General Translation: ```text title="Output" count key-by-key (one, other) complete (one, few, many, other) 1 У вас 1 непрочитанное сообщение. У вас 1 непрочитанное сообщение. 3 У вас 3 непрочитанных сообщений. У вас 3 непрочитанных сообщения. 5 У вас 5 непрочитанных сообщений. У вас 5 непрочитанных сообщений. 22 У вас 22 непрочитанных сообщений. У вас 22 непрочитанных сообщения. ``` La [guida di Rails](https://guides.rubyonrails.org/i18n.html#locale-specific-rules) precisa che per impostazione predefinita si applicano solo le regole del plurale dell'inglese; le altre vengono aggiunte dal backend `Pluralization` di I18n o dalla gem rails-i18n. Le tabelle di traduzione di Hugo usano le stesse categorie CLDR, da `zero` a `other`. ### La radice dell'impostazione regionale va cambiata In Rails, un file tradotto che inizia ancora con `en:` non genera errori: viene semplicemente caricato come inglese. In un test con la gem i18n, un file spagnolo lasciato con radice `en:` ha sostituito il titolo inglese con quello spagnolo, e `I18n.t` per `es` ha restituito un messaggio di traduzione mancante. Rinomina la radice in ogni file tradotto e mantieni `config.i18n.available_locales` sincronizzato. ## Modi per tradurre i file di impostazioni regionali YAML | Approccio | Chiavi e segnaposto | Chiavi plurali | Contesto per stringhe brevi | Gestione delle modifiche | | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- | | A mano | Sicuro se il traduttore conosce YAML | Aggiunte se il traduttore conosce le regole della lingua | Il traduttore può chiedere | Manuale a ogni modifica | | [i18n-tasks](https://github.com/glebm/i18n-tasks) `translate-missing` (Rails) con Google Translate, DeepL o OpenAI | Sostituisce `%{...}` con token prima dell'invio | `missing` segnala le forme plurali assenti quando sono caricate le regole di rails-i18n | Opzioni e prompt specifici per ogni backend | Compila le chiavi mancanti; il testo inglese modificato non viene ritradotto | | Un sistema di gestione delle traduzioni (TMS) | Analizzati sintatticamente in base al formato | Dipende dal TMS | Screenshot, commenti, glossario | Sincronizzazione con il repository o scambio di file | | Uno script LLM che elabora il file | Di solito preservati, ma nulla garantisce le virgolette | Aggiunte solo se le richiedi esplicitamente | Ciò che inserisci nel prompt | Riesegui e valida ogni volta | | [La CLI di General Translation](/docs/cli/reference/formats/yaml-files) | Traduce solo i valori stringa; le chiavi restano invariate | Traduce le chiavi presenti nella sorgente | Glossario, Prompt Personalizzati, metadati per chiave | Riutilizza le traduzioni invariate a ogni esecuzione | Per uno o due file di piccole dimensioni, basta modificarli a mano. Usa i18n-tasks quando un'app Rails ha bisogno di controlli sulle chiavi mancanti e ti va bene colmare le lacune con una traduzione automatica da revisionare personalmente. (Consulta [General Translation vs. i18n-tasks](/kb/general-translation-vs-i18n-tasks) per capire come i due strumenti si integrano.) Usa un [TMS](/kb/what-is-a-translation-management-system) quando i file sono gestiti dai traduttori. Usa General Translation quando ogni file di impostazioni regionali deve essere rigenerato man mano che il testo inglese cambia, con una terminologia condivisa tra app, documentazione e sito di marketing. ## Tradurre file YAML con General Translation La CLI di General Translation, `gt`, traduce i file `.yaml` e `.yml` tramite una voce `yaml` in `gt.config.json`. Il segnaposto `[locale]` indica la posizione della lingua, quindi i formati che includono l'impostazione regionale nel nome del file funzionano senza modifiche. Per Symfony, `translations/*.[locale].yaml` associa `messages+intl-icu.en.yaml` a `messages+intl-icu.fr.yaml`; per Hugo: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["de", "pt-BR"], "files": { "yaml": { "include": ["i18n/[locale].yaml"] } } } ``` Verificato con `gt` 2.26.11, la risoluzione dei percorsi della CLI associa `i18n/en.yaml` a `i18n/de.yaml` e `i18n/pt-BR.yaml`, in linea con i nomi file basati sui tag di lingua usati da Hugo. Accedi con [`npx gt login`](/docs/cli/reference/commands/login) e imposta un ID progetto ([credenziali della CLI](/docs/cli/guides/configuring#credentials)), importa eventuali traduzioni esistenti con [`npx gt upload`](/docs/cli/reference/commands/upload), quindi esegui [`npx gt translate`](/docs/cli/reference/commands/translate). General Translation traduce i valori stringa e lascia invariato tutto il resto: chiavi, numeri, booleani e commenti restano al loro posto, e un blocco con ancora viene tradotto una sola volta, mentre i suoi alias continuano a puntarvi. Alcuni dettagli specifici del framework restano quindi a tuo carico: * **Radici delle impostazioni regionali in Rails.** La CLI non rinomina le chiavi, compresa la `en:` di primo livello, e l'opzione [`transform`](/docs/cli/reference/config#files) rinomina i file di output, non le chiavi. Usa con la CLI file di lavoro senza radice, come `translations/en.yml`, e aggiungi la radice dell'impostazione regionale quando li esporti in `config/locales`. (Consulta [General Translation vs. Rails I18n](/kb/general-translation-vs-rails-i18n) per un breve script di esportazione.) * **Chiavi plurali.** La CLI traduce le chiavi plurali presenti nella sorgente, quindi un file russo generato da una sorgente inglese con `one`/`other` conterrà solo `one` e `other`. Esegui `i18n-tasks missing` con rails-i18n caricato per individuare le chiavi `few` e `many` ancora da aggiungere. * **`yes`, `no`, `on` e `off` senza virgolette.** General Translation analizza il YAML secondo le regole della versione 1.2, in cui questi valori sono stringhe e vengono quindi tradotti come testo. Racchiudili tra virgolette nella sorgente, come faresti comunque per Rails. * **Sintassi della libreria.** La sintassi personalizzata delle stringhe, come i messaggi ICU, è supportata per `i18next` e `next-intl`; per le altre librerie, controlla le stringhe con sintassi personalizzata dopo la prima esecuzione. Per disambiguare una stringa breve come "Salva", aggiungi un file `.metadata.yaml` associato con una nota `context` o un limite `maxChars` per ciascuna chiave ([metadati associati alle chiavi](/docs/cli/reference/formats/yaml-files#metadata)). Un Glossario e dei Prompt Personalizzati in un [gruppo di contesto](/docs/platform/dashboard/guides/defining-context-for-translations) mantengono coerenti i termini di prodotto nei tuoi cataloghi YAML e in tutti gli altri progetti del gruppo, mentre i revisori possono [modificare le traduzioni nella dashboard](/docs/platform/dashboard/guides/reviewing-translations). Se qualcuno modifica in locale un file tradotto, esegui [`npx gt save-local`](/docs/cli/reference/commands/save-local) prima dell'esecuzione successiva, in modo che le modifiche non vengano sovrascritte. Dopo ogni esecuzione, carica i file come fa la tua app: `i18n-tasks missing` e `i18n-tasks check-consistent-interpolations` per Rails, `lint:translations` per Symfony e una build per Hugo. (Consulta [General Translation vs. Symfony Translation](/kb/general-translation-vs-symfony-translation) per la configurazione di Symfony e [Come si traducono i file JSON di i18n?](/kb/translate-json-files) se i tuoi cataloghi sono in JSON.) ## Domande frequenti ### Devo racchiudere tra virgolette ogni valore in un file YAML di impostazioni regionali? Racchiudere ogni valore tra virgolette è l'abitudine più sicura. Un valore tra virgolette doppie è sempre una stringa: in questo modo i due punti, un `%{name}` iniziale e parole come `No` non possono alterare il parsing del file, né prima né dopo la traduzione. ### Perché la mia app Rails segnala "translation missing" per una lingua che ho tradotto? Per prima cosa, controlla la chiave di primo livello del file. Un file che ha ancora `en:` come radice viene caricato come inglese, quindi la nuova impostazione regionale risulta priva di chiavi. Verifica inoltre che l'impostazione regionale sia inclusa in `config.i18n.available_locales`. ### Posso usare ancore e alias nei file delle impostazioni regionali? Rails li carica, ma alcuni loader no, tra cui unplugin-vue-i18n per vue-i18n. Tradurre un valore ancorato modifica tutti gli alias che vi fanno riferimento, quindi usali solo per testi che devono essere identici ovunque. ## Punti chiave * Traduci solo i valori; le chiavi, i segnaposto come `%{name}` e `{{name}}` e l'indentazione dei blocchi restano invariati. * Racchiudi tra virgolette i valori che contengono due punti, che iniziano con `%` o `{` oppure che sono parole come `yes`, `no`, `on` e `off`: senza virgolette, Ruby li interpreta come booleani. * Russo e polacco richiedono le chiavi `few` e `many`, assenti in una sorgente inglese; se mancano, Rails ripiega silenziosamente su `other`. * Ogni file Rails ha bisogno di una propria radice di impostazione regionale: un file spagnolo con radice `en:` viene caricato come inglese. * La CLI di General Translation traduce i valori stringa YAML con `"yaml": { "include": [...] }` e [`npx gt translate`](/docs/cli/reference/commands/translate), preservando chiavi, commenti e ancore; delle radici Rails e delle chiavi plurali mancanti resti comunque responsabile tu. ## Related questions - [General Translation vs. Rails I18n: servono entrambi?](https://generaltranslation.com/it/kb/general-translation-vs-rails-i18n.mdx): Rails I18n recupera i messaggi e formatta date e numeri. General Translation genera le traduzioni, le mantiene aggiornate man mano che il testo in inglese cambia e offre al tuo team una Dashboard per la revisione. Usali insieme per distribuire cataloghi Rails tradotti a ogni rilascio. - [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. - [General Translation o Symfony Translation: quale scegliere?](https://generaltranslation.com/it/kb/general-translation-vs-symfony-translation.mdx): Symfony Translation renderizza i messaggi in PHP e Twig. General Translation traduce i suoi cataloghi YAML in CI, li mantiene aggiornati man mano che la sorgente cambia e offre ai revisori una Dashboard per modificarli. Mantieni il rendering di Symfony e aggiungi la traduzione automatica al tuo flusso di lavoro di rilascio. - [Come si traducono i file JSON di i18n?](https://generaltranslation.com/it/kb/translate-json-files.mdx): 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. - [Come si traducono i file PO e POT?](https://generaltranslation.com/it/kb/translate-po-files.mdx): Compila ogni msgstr, incluse tutte le forme plurali richieste dall'intestazione Plural-Forms, e lascia invariati msgid, msgctxt e i segnaposto. Esegui msgfmt --check per verificare intestazioni, numero di forme plurali e segnaposto nelle voci con un flag di formato, e controlla a parte che nessun msgstr sia vuoto. La CLI di General Translation genera un file PO tradotto per ogni lingua a partire dal tuo template POT. ## Previous and next questions - Previous question: [Come si traducono i file .resx in un'app .NET?](https://generaltranslation.com/it/kb/translate-resx-files.mdx) - Next question: [Come si traducono i file PO e POT?](https://generaltranslation.com/it/kb/translate-po-files.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/it/kb/sitemap.md) for every article.