# gt: General Translation CLI tool: Metadati per chiave URL: https://generaltranslation.com/it/docs/cli/reference/keyed-metadata.mdx --- title: Metadati per chiave description: Metadati di traduzione per chiave nei file JSON e YAML --- ## Panoramica I metadati per chiave ti consentono di associare istruzioni di traduzione a singole chiavi nei tuoi file JSON e YAML. Devi fornire un file `.metadata.json` o `.metadata.yaml` associato che rispecchi la struttura delle chiavi del file sorgente, con oggetti di metadati a livello delle foglie terminali. La CLI rileva automaticamente i file associati, li convalida rispetto alla struttura del file sorgente e li invia al motore di traduzione. *** ## Struttura del file Un file di metadati associato deve: * Trovarsi nella stessa directory del file sorgente * Rispettare la convenzione di denominazione `{name}.metadata.{ext}` (ad esempio, `translations.metadata.json` per `translations.json`) * Rispecchiare la struttura delle chiavi del file sorgente ``` translations.json # stringhe sorgente translations.metadata.json # metadati per chiave ``` Il file di metadati rispecchia la struttura delle chiavi di origine, con oggetti di metadati nei nodi foglia anziché stringhe: ```json title="translations.json" { "nav": { "home": "Home", "bank": "Bank", "save": "Save" }, "alerts": { "new_lead": "You have a new lead!" } } ``` ```json title="translations.metadata.json" { "nav": { "bank": { "context": "Riverbank — the side of a river. NOT a financial institution." }, "save": { "context": "Sports term — a goalkeeper preventing a goal. NOT saving data.", "maxChars": 12 } }, "alerts": { "new_lead": { "context": "Sales/CRM context. A 'lead' is a potential customer.", "maxChars": 30 } } } ``` Non tutte le chiavi richiedono metadati: `home` non ha alcuna voce qui sopra e viene tradotta normalmente. Inserisci voci solo per le chiavi che richiedono istruzioni di traduzione specifiche. *** ## Riferimento dei campi | Campo | Tipo | Obbligatorio | Descrizione | | ------------ | --------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------- | | `context` | `string` | No | Istruzioni di traduzione per questa specifica stringa | | `maxChars` | `number` | No | Numero massimo di caratteri dell'output tradotto | | `sourceCode` | `Record` | No | Contesto del codice sorgente circostante, organizzato per percorso del file | *** ## Campi ### `context` Tipo: `string` Istruzioni di traduzione applicate a una determinata stringa. Usalo per disambiguare parole con più significati, specificare la terminologia di dominio o chiarire l'interpretazione desiderata. ```json { "bank": { "context": "Riverbank. The side of a river where land meets water, NOT a financial institution." } } ``` ### `maxChars` Tipo: `number` Un limite massimo di caratteri per l'output tradotto. Il motore userà sinonimi più brevi, abbreviazioni o formulazioni concise per rientrare nel limite. Si tratta di un tentativo nei limiti del possibile. Se il limite non è realizzabile per il contenuto di origine, viene restituita la traduzione completa. ```json { "save": { "maxChars": 10 } } ``` ### `sourceCode` Tipo: `Record` Contesto del codice sorgente circostante per una stringa. È indicizzato per percorso del file e ogni voce contiene: * `before` — righe di codice sorgente sopra la riga di destinazione * `target` — la riga che contiene la stringa da tradurre * `after` — righe di codice sorgente sotto la riga di destinazione Sono supportate più voci per file se la stessa stringa compare in posizioni diverse. ```json { "new_lead": { "sourceCode": { "components/Dashboard.tsx": [ { "before": "function NotificationBanner({ type }) {\n const gt = useGT();", "target": " const msg = gt('You have a new lead!');", "after": " return {msg};\n}" } ] } } } ``` ### Esempio combinato Tutti e tre i campi in una singola chiave: ```json { "save_button": { "context": "Sports term. A goalkeeper's save — preventing a goal from being scored. NOT saving data.", "maxChars": 12, "sourceCode": { "components/MatchStats.tsx": [ { "before": "const stats = useMatchStats();\nconst gt = useGT();", "target": "const label = gt('Save');", "after": "return }>{label}: {stats.saves};" } ] } } } ``` *** ## YAML Funziona allo stesso modo con i file associati `.metadata.yaml` o `.metadata.yml`: ```yaml title="translations.metadata.yaml" ui: buttons: save: context: "Sports term. A goalkeeper's save, NOT saving data." maxChars: 12 draft: context: "Beer on tap, as in 'draft beer'. NOT a document version." labels: date: context: "The edible fruit of the date palm. NOT a calendar date." ``` *** ## Convalida La CLI convalida il file dei metadati rispetto alla struttura del file sorgente. Il processo termina con un errore se: * Una chiave di metadati non esiste nel file sorgente * Un valore di metadati è un tipo primitivo dove il file sorgente contiene un oggetto annidato * Un valore di metadati è un array dove il file sorgente contiene un oggetto (o viceversa) * Il tipo radice (array o oggetto) non corrisponde a quello del file sorgente * Il file dei metadati non può essere analizzato *** ## Supporto per gli schemi I metadati per chiave funzionano con gli schemi JSON (`include` e `composite`) e con gli schemi YAML (`include`). I metadati vengono trasformati automaticamente tramite la stessa pipeline degli schemi del contenuto sorgente, così che i percorsi delle chiavi risultino allineati al momento della traduzione, indipendentemente dalla struttura del file. *** ## Filtraggio dei file companion I file associati vengono associati automaticamente al file sorgente corrispondente. Non vengono tradotti come file autonomi. Questo vale solo se il file sorgente corrispondente è presente nell'elenco dei file. Un file `.metadata.json` senza un file sorgente corrispondente viene trattato come un normale file. *** ## Comportamento della ritraduzione Le modifiche al solo file di metadati non attivano la ritraduzione se il contenuto sorgente non è cambiato. Per applicare i metadati aggiornati, deve cambiare anche il contenuto sorgente.