# gt: General Translation CLI tool: Metadati per chiave
URL: https://generaltranslation.com/it/docs/cli/reference/keyed-metadata.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Aggiungi istruzioni di traduzione per chiave ai file JSON e YAML di General Translation. Riferimento API per i metadati per chiave.
Fornisci un file di metadati associato che rispecchia la struttura delle chiavi del file sorgente, con un oggetto di metadati in ogni nodo foglia. Ogni oggetto contiene istruzioni per la traduzione di quella singola chiave.
La CLI rileva automaticamente i file di metadati associati, li valida rispetto alla struttura sorgente e li invia al motore di traduzione.
## Campi [#fields]
| Campo | Descrizione | Tipo | Facoltativo | Predefinito |
| ---------------------------- | ----------------------------------------------------------------------------------------- | --------- | ----------- | ----------- |
| [`context`](#context) | Istruzioni di traduzione per una specifica stringa. | `string` | Sì | — |
| [`maxChars`](#max-chars) | Lunghezza massima richiesta per le traduzioni generate. | `integer` | Sì | — |
| [`sourceCode`](#source-code) | Contesto del codice sorgente circostante, con chiavi corrispondenti al percorso del file. | `object` | Sì | — |
## Struttura del file [#structure]
Un file di metadati associato deve trovarsi nella stessa directory del file sorgente, rispettare la convenzione di denominazione `{name}.metadata.{ext}` e rispecchiare la struttura delle chiavi del file sorgente con un oggetto di metadati in ogni nodo foglia.
```text
translations.json # stringhe sorgente
translations.metadata.json # metadati per chiave
```
Inserisci voci solo per le chiavi che richiedono istruzioni. Le chiavi senza alcuna voce vengono tradotte normalmente.
```json title="translations.json"
{
"nav": {
"home": "Home",
"bank": "Bank",
"save": "Save"
}
}
```
```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
}
}
}
```
## `context` [#context]
**Tipo** `string` · **Facoltativo** · **Predefinito** —
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` [#max-chars]
**Tipo** `integer` · **Facoltativo** · **Predefinito** —
Un numero massimo di caratteri, espresso come intero positivo, richiesto al motore di traduzione. 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 sorgente, viene restituita la traduzione completa. I valori zero, negativi e frazionari vengono ignorati.
```json
{
"save": {
"maxChars": 10
}
}
```
## `sourceCode` [#source-code]
**Tipo** `object` · **Facoltativo** · **Predefinito** —
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) e `after` (righe di codice sorgente sotto la riga di destinazione). Sono supportate più voci per file quando la stessa stringa compare in posizioni diverse.
Il servizio di traduzione utilizza al massimo cinque voci per file. Tronca ogni valore `before` e `after` a 2.000 caratteri e ogni valore `target` a 500 caratteri.
```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 [#yaml]
I metadati funzionano 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
labels:
date:
context: "The edible fruit of the date palm. NOT a calendar date."
```
## Validazione [#validation]
La CLI valida il file di metadati rispetto alla struttura sorgente e termina con un errore se una chiave di metadati non esiste nella sorgente, se il tipo di un valore non corrisponde a quello della sorgente (primitivo invece di oggetto, array invece di oggetto), se il tipo radice non corrisponde o se il file non può essere analizzato.
La CLI non rifiuta valori numerici `maxChars` non validi. Il motore di traduzione applica solo numeri interi positivi e considera gli altri numeri come se non fosse impostato alcun limite.
## Schema e corrispondenza [#schema]
I metadati per chiave funzionano con gli schemi JSON (`include` e `composite`) e YAML (`include`); i metadati vengono trasformati attraverso la stessa pipeline degli schemi, così i percorsi delle chiavi risultano allineati al momento della traduzione. I file associati vengono abbinati al rispettivo file sorgente e non vengono tradotti autonomamente: un file `.metadata.json` senza un file sorgente corrispondente viene trattato come un file normale. Modificare solo i metadati non attiva una nuova traduzione; deve cambiare anche il contenuto sorgente.
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.