# 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: Ajoutez des instructions de traduction par clé aux fichiers JSON et YAML de General Translation. Référence API des métadonnées par clé.

---

Vous fournissez un fichier de métadonnées compagnon qui reproduit la structure des clés du fichier source, avec un objet de métadonnées à chaque feuille. Chaque objet contient des instructions pour la traduction de cette clé.

La CLI détecte automatiquement les fichiers de métadonnées compagnons, les valide par rapport à la structure du source et les envoie au moteur de traduction.

## Champs [#fields]

| Champ                        | Description                                                                  | Type     | Facultatif | Par défaut |
| ---------------------------- | ---------------------------------------------------------------------------- | -------- | ---------- | ---------- |
| [`context`](#context)        | Instructions de traduction pour une chaîne spécifique.                       | `string` | Oui        | —          |
| [`maxChars`](#max-chars)     | Nombre maximal de caractères dans la sortie traduite.                        | `number` | Oui        | —          |
| [`sourceCode`](#source-code) | Contexte du code source environnant, avec les chemins de fichier comme clés. | `object` | Oui        | —          |

## Structure du fichier [#structure]

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}` et refléter la structure des clés du fichier source, avec un objet de métadonnées à chaque feuille.

```text
translations.json           # chaînes sources
translations.metadata.json  # métadonnées par clé
```

Ne fournissez des entrées que pour les clés qui nécessitent des instructions. Les clés sans entrée se traduisent normalement.

```json title="translations.json"
{
  "nav": {
    "home": "Home",
    "bank": "Bank",
    "save": "Save"
  }
}
```

```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
    }
  }
}
```

## `context` [#context]

**Type** `string` · **Facultatif** · **Par défaut** —

Instructions 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` [#max-chars]

**Type** `number` · **Facultatif** · **Par défaut** —

Applique une limite maximale de caractères à la traduction générée. Le moteur utilise des synonymes plus courts, des abréviations ou une formulation concise pour respecter cette limite. Cela s’applique dans la mesure du possible : si cette limite est impossible à respecter pour le contenu source, la traduction complète est renvoyée.

```json
{
  "save": {
    "maxChars": 10
  }
}
```

## `sourceCode` [#source-code]

**Type** `object` · **Facultatif** · **Par défaut** —

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) et `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 <Banner variant=\"success\">{msg}</Banner>;\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 <StatBadge icon={<GoalkeeperIcon />}>{label}: {stats.saves}</StatBadge>;"
        }
      ]
    }
  }
}
```

## YAML [#yaml]

Les métadonnées fonctionnent 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
  labels:
    date:
      context: "Le fruit comestible du palmier dattier. PAS une date de calendrier."
```

## Validation [#validation]

Le CLI valide le fichier de métadonnées par rapport à la structure de la source et renvoie une erreur si une clé de métadonnées n’existe pas dans la source, si un type de valeur ne correspond pas à celui de la source (type primitif vs. objet, tableau vs. objet), si le type racine ne correspond pas, ou si le fichier ne peut pas être analysé.

## Schéma et correspondance [#schema]

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 passent par le même pipeline de schémas afin que les chemins de clés correspondent au moment de la traduction. Les fichiers compagnons sont associés à leur fichier source et ne sont pas traduits séparément — un fichier `.metadata.json` sans fichier source correspondant est traité comme un fichier ordinaire. Modifier uniquement les métadonnées ne déclenche pas de nouvelle traduction ; le contenu source doit également changer.