Vue d’ensemble

gtx-cli 2.10.0 ajoute la prise en charge des métadonnées par clé dans les fichiers de traduction JSON et YAML. Il s’agit d’instructions de traduction associées à chaque clé, qui vous offrent un contrôle précis sur la façon dont chaque chaîne est traduite.

Jusqu’à présent, le contexte de traduction des fichiers à clés était défini au niveau du projet. Les contrôles de style, les entrées de glossaire et les règles propres au paramètre régional s’appliquaient globalement à l’ensemble de votre contenu. Les métadonnées par clé vous permettent d’aller plus loin en associant directement des indications de traduction spécifiques à chaque clé de vos fichiers.

À quoi cela ressemble

Vous créez un fichier de métadonnées compagnon situé à côté de votre fichier source et qui en reprend la structure de clés. Au niveau des feuilles, au lieu de chaînes de caractères, vous fournissez des objets de métadonnées contenant des instructions de traduction :

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

{
  "nav": {
    "home": {
      "context": "Terme de baseball — le marbre sur un terrain. PAS une maison."
    },
    "bank": {
      "context": "Berge — le bord d'une rivière. PAS un établissement financier."
    },
    "save": {
      "context": "Terme sportif — un gardien de but arrêtant un tir. PAS une sauvegarde de données.",
      "maxChars": 12
    }
  },
  "alerts": {
    "new_lead": {
      "context": "Contexte ventes/CRM. Un 'lead' est un client potentiel.",
      "maxChars": 30
    }
  }
}

Le fichier compagnon doit se trouver dans le même répertoire que le fichier source et respecter la convention de nommage {name}.metadata.json (ou .metadata.yaml pour les fichiers YAML). Le CLI le détecte automatiquement lorsque vous exécutez npx gt translate.

Avec un contexte par clé, "Bank" se traduit par "Ribera" (berge) plutôt que par le possible "Banco" (établissement financier), et "Save" devient "Parada" (arrêt du gardien) plutôt que "Guardar" (stocker). Pour les chaînes déjà sans ambiguïté, vous n’avez pas besoin de fournir de métadonnées — ajoutez des entrées uniquement pour les clés qui en bénéficient.

Champs pris en charge

Nous prenons actuellement en charge trois champs de métadonnées :

• context — instructions de traduction pour une chaîne donnée. C'est le champ le plus important : utilisez-le pour lever les ambiguïtés, préciser la terminologie du domaine ou clarifier l'intention.
• maxChars — nombre maximal de caractères dans la traduction générée. Il s'agit d'une contrainte appliquée dans la mesure du possible : le moteur utilisera des synonymes plus courts et une formulation concise pour s'y conformer, mais il ne tronquera pas une traduction pour la faire tenir dans une longueur irréaliste.
• sourceCode — contexte du code source entourant une chaîne. Il vous permet de montrer au moteur où et comment la chaîne est utilisée dans votre base de code, ce qui l'aide à faire de meilleurs choix de ton, de terminologie et de formulation.

Tous les champs sont facultatifs pour chaque clé. Pour plus de détails et des exemples pour chaque champ, consultez la référence des métadonnées par clé.

Prise en charge du YAML

La même approche fonctionne pour les fichiers YAML. Créez un fichier compagnon .metadata.yaml avec la même structure de clés :

ui:
  buttons:
    save:
      context: "Terme sportif — l'arrêt d'un gardien de but. PAS une sauvegarde de données."
    draft:
      context: "Bière à la pression, comme dans 'bière pression'. PAS une version de document."
  labels:
    date:
      context: "Le fruit comestible du palmier dattier. PAS une date de calendrier."
    chips:
      context: "Anglais britannique : frites (pommes de terre). PAS des chips ou des microprocesseurs."