# gt: General Translation CLI tool: Metadati per chiave
URL: https://generaltranslation.com/it/docs/cli/reference/keyed-metadata.mdx
---

title: Metadati per chiave
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)     | Numero massimo di caratteri per l'output tradotto.                                    | `number` | 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** `number` · **Facoltativo** · **Predefinito** —

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` [#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.

```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 <Banner variant=\"success\">{msg}</Banner>;\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 <StatBadge icon={<GoalkeeperIcon />}>{label}: {stats.saves}</StatBadge>;"
        }
      ]
    }
  }
}
```

## 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.

## 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.