# gt: General Translation CLI tool: Métadonnées par clé URL: https://generaltranslation.com/fr/docs/cli/reference/keyed-metadata.mdx --- title: Métadonnées par clé description: Métadonnées de traduction par clé dans les fichiers JSON et YAML --- ## Vue d’ensemble Les métadonnées par clé vous permettent d’associer des instructions de traduction à des clés individuelles dans vos fichiers JSON et YAML. Vous fournissez un fichier compagnon `.metadata.json` ou `.metadata.yaml` qui reprend la structure des clés du fichier source, avec des objets de métadonnées au niveau des feuilles. Le CLI détecte automatiquement les fichiers de métadonnées compagnons, les valide par rapport à la structure du fichier source et les envoie au moteur de traduction. *** ## Structure du fichier Un fichier de métadonnées compagnon doit : * Se trouver dans le même répertoire que le fichier source * Respecter la convention de nommage `{name}.metadata.{ext}` (par ex., `translations.metadata.json` pour `translations.json`) * Reproduire la structure des clés du fichier source ``` translations.json # chaînes sources translations.metadata.json # métadonnées par clé ``` Le fichier de métadonnées reflète la structure des clés source, avec des objets de métadonnées aux feuilles au lieu de chaînes de caractères : ```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": { "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 } } } ``` Toutes les clés n’ont pas besoin de métadonnées — `home` n’a pas d’entrée ci-dessus et se traduit normalement. Ne fournissez des entrées que pour les clés qui nécessitent des consignes de traduction spécifiques. *** ## Référence des champs | Champ | Type | Obligatoire | Description | | ------------ | --------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | | `context` | `string` | Non | Instructions de traduction pour cette chaîne | | `maxChars` | `number` | Non | Nombre maximal de caractères du texte traduit | | `sourceCode` | `Record` | Non | Contexte du code source environnant, indexé par chemin de fichier | *** ## Champs ### `context` Type : `string` Consignes de traduction appliquées à une chaîne donnée. Utilisez ce champ pour lever l’ambiguïté des mots polysémiques, préciser la terminologie du domaine ou clarifier l’interprétation attendue. ```json { "bank": { "context": "Riverbank. The side of a river where land meets water, NOT a financial institution." } } ``` ### `maxChars` Type : `number` Applique une limite maximale de caractères à la traduction générée. Le moteur utilisera des synonymes plus courts, des abréviations ou une formulation concise pour respecter cette limite. Il s’agit d’un effort au mieux. Si cette limite est impossible à respecter pour le contenu source, la traduction complète est renvoyée. ```json { "save": { "maxChars": 10 } } ``` ### `sourceCode` Type : `Record` Contexte de code source autour d’une chaîne. Indexé par chemin de fichier ; chaque entrée contient : * `before` — les lignes de code source au-dessus de la ligne cible * `target` — la ligne contenant la chaîne en cours de traduction * `after` — les lignes de code source sous la ligne cible Plusieurs entrées par fichier sont prises en charge si la même chaîne apparaît à différents emplacements. ```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 {msg};\n}" } ] } } } ``` ### Exemple combiné Les trois champs dans une seule clé : ```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 }>{label}: {stats.saves};" } ] } } } ``` *** ## YAML Fonctionne de la même manière avec les fichiers `.metadata.yaml` ou `.metadata.yml` compagnons : ```yaml title="translations.metadata.yaml" ui: buttons: save: context: "Terme sportif. L'arrêt d'un gardien de but, PAS une sauvegarde de données." maxChars: 12 draft: context: "Bière pression, comme dans 'bière à la pression'. PAS une version de document." labels: date: context: "Le fruit comestible du palmier dattier. PAS une date de calendrier." ``` *** ## Validation La CLI valide le fichier de métadonnées par rapport à la structure du fichier source. Le processus se termine par une erreur si : * Une clé de métadonnées n’existe pas dans le fichier source * Une valeur de métadonnées est un type primitif alors que la source contient un objet imbriqué * Une valeur de métadonnées est un tableau alors que la source contient un objet (ou inversement) * Le type racine (tableau ou objet) ne correspond pas à celui de la source * Le fichier de métadonnées ne peut pas être analysé *** ## Prise en charge des schémas Les métadonnées par clé fonctionnent avec les schémas JSON (`include` et `composite`) et les schémas YAML (`include`). Les métadonnées sont automatiquement transformées par le même pipeline de schéma que le contenu source, afin que les chemins des clés correspondent au moment de la traduction, quelle que soit la structure du fichier. *** ## Filtrage des fichiers compagnons Les fichiers de métadonnées compagnons sont automatiquement associés à leur fichier source correspondant. Ils ne sont pas traduits en tant que fichiers autonomes. Cela s’applique uniquement lorsque le fichier source correspondant figure dans la liste des fichiers. Un fichier `.metadata.json` sans fichier source correspondant est traité comme un fichier classique. *** ## Comportement de retraduction Les modifications du seul fichier de métadonnées ne déclenchent pas de retraduction si le contenu source n’a pas changé. Pour appliquer les métadonnées mises à jour, le contenu source doit lui aussi être modifié.