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 complementare 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:

{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  },
  "alerts": {
    "new_lead": "You have a new lead!"
  }
}

{
  "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.

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.

Supporto per YAML

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

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