# General Translation Changelog: gtx-cli 2.10.0: Istruzioni di traduzione per chiave
URL: https://generaltranslation.com/it/blog/gtx-cli_v2_10_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Fernando Aviles
Published: 2026-03-12

## Panoramica

**gtx-cli 2.10.0** aggiunge il supporto ai **metadati per chiave** nei file di traduzione JSON e YAML. Si tratta di istruzioni di traduzione per singola chiave che ti consentono di controllare in modo granulare come vengono tradotte le singole stringhe.

Fino a ora, il contesto di traduzione per i file basati su chiavi operava a livello di progetto. I controlli di stile, le voci del glossario e le regole specifiche per impostazione regionale si applicavano in modo generale a tutti i contenuti. I metadati per chiave ti permettono di spingerti a un livello più in profondità, associando suggerimenti di traduzione specifici direttamente alle singole chiavi nei tuoi file.

***

## Ecco come si presenta

Crei un file di metadati associato accanto al file sorgente, che ne rispecchia la struttura delle chiavi. A livello di foglia, anziché stringhe, fornisci oggetti di metadati con istruzioni per la traduzione:

```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": {
    "home": {
      "context": "Termine del baseball — home plate su un diamante. NON una casa."
    },
    "bank": {
      "context": "Riva del fiume — il lato di un fiume. NON un istituto finanziario."
    },
    "save": {
      "context": "Termine sportivo — un portiere che para un gol. NON il salvataggio di dati.",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "Contesto vendite/CRM. Un 'lead' è un potenziale cliente.",
      "maxChars": 30
    }
  }
}
```

Il file associato deve trovarsi nella stessa directory del file sorgente e seguire la convenzione di denominazione `{name}.metadata.json` (oppure `.metadata.yaml` per i file YAML). La CLI lo rileva automaticamente quando esegui [`npx gt translate`](/docs/cli/reference/commands/translate).

Con il contesto per chiave, "Bank" viene tradotto come "Ribera" (riva del fiume) invece del possibile "Banco" (istituzione finanziaria), e "Save" diventa "Parada" (parata del portiere) invece di "Guardar" (memorizzare). Per le stringhe già prive di ambiguità, non è affatto necessario fornire metadati: aggiungi voci solo per le chiavi che ne traggono vantaggio.

***

## Campi supportati

Al momento supportiamo tre campi di metadati:

* **`context`** — istruzioni di traduzione per una stringa specifica. È il campo più importante: usalo per disambiguare i termini, specificare la terminologia di dominio o chiarire l'intento.
* **`maxChars`** — un limite massimo di caratteri per l'output tradotto. Viene applicato nei limiti del possibile: il motore userà sinonimi più brevi e una formulazione concisa per rientrare nel limite, ma non troncherà una traduzione fino a renderla irrealizzabile.
* **`sourceCode`** — il contesto del codice sorgente che circonda una stringa. Ti permette di mostrare al motore dove e come la stringa viene usata nel tuo codebase, aiutandolo a prendere decisioni migliori su tono, terminologia e formulazione.

Tutti i campi sono facoltativi per ogni chiave. Per informazioni complete ed esempi di ciascun campo, consulta il [riferimento dei metadati per chiave](/docs/cli/reference/keyed-metadata).

***

## Supporto per YAML

Lo stesso approccio funziona per i file YAML. Crea un file `.metadata.yaml` associato con la stessa struttura di chiavi:

```yaml title="translations.metadata.yaml"
ui:
  buttons:
    save:
      context: "Sports term — a goalkeeper's save. NOT saving data."
    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."
    chips:
      context: "British English: hot fried potato strips (french fries). NOT crisps or microchips."
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.