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 offrono un controllo granulare su come vengono tradotte le singole stringhe.

Fino a ora, il contesto di traduzione per i file con chiavi operava a livello di progetto. I controlli di stile, le voci del glossario e le regole specifiche per ogni lingua o variante locale si applicavano in modo generalizzato a tutti i contenuti. I metadati per chiave ti permettono di scendere a un livello più in profondità, associando suggerimenti di traduzione specifici direttamente alle singole chiavi nei file.

Come si presenta

Crei un file di metadati complementare che si trova accanto al file sorgente e ne rispecchia la struttura delle chiavi. Al livello delle foglie, invece di 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": "Baseball term — home plate on a diamond. NOT a house."
    },
    "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
    }
  }
}

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). L'interfaccia a riga di comando (CLI) lo rileva automaticamente quando esegui npx gt translate.

Con il contesto per chiave, "Bank" viene tradotto come "Ribera" (sponda 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 è necessario fornire metadati: aggiungi voci solo per le chiavi che ne traggono vantaggio.

Campi supportati

Attualmente supportiamo tre campi di metadati:

• context — istruzioni di traduzione per una stringa specifica. È il campo più importante: usalo per disambiguare parole, 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 formulazioni concise per rientrare nel limite, ma non troncherà una traduzione fino a una lunghezza irrealizzabile.
• sourceCode — il contesto del codice sorgente circostante per una stringa. Ti permette di mostrare al motore dove e come la stringa viene usata nel tuo codebase, aiutandolo così a prendere decisioni migliori su tono, terminologia e formulazione.

Tutti i campi sono opzionali per ogni chiave. Per dettagli completi ed esempi di ogni campo, consulta il riferimento dei metadati per chiave.

Supporto per YAML

Lo stesso approccio funziona anche per i file YAML. Crea un file associato .metadata.yaml 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."