# gt: General Translation CLI tool: Métadonnées par clé
URL: https://generaltranslation.com/fr/docs/cli/reference/keyed-metadata.mdx
Docs index: https://generaltranslation.com/llms.txt
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) | Longueur maximale demandée pour les traductions générées. | `integer` | Oui | — |
| [`sourceCode`](#source-code) | contexte de 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** `integer` · **Facultatif** · **Par défaut** —
Nombre maximal de caractères, sous la forme d’un entier positif, demandé au moteur de traduction. 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. Les valeurs nulles, négatives et fractionnaires sont ignorées.
```json
{
"save": {
"maxChars": 10
}
}
```
## `sourceCode` [#source-code]
**Type** `object` · **Facultatif** · **Par défaut** —
Contexte de code source environnant 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.
Le service de traduction utilise au maximum cinq entrées par fichier. Il tronque chaque valeur `before` et `after` à 2 000 caractères et chaque valeur `target` à 500 caractères.
```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 [#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é.
Le CLI ne rejette pas les valeurs numériques `maxChars` non valides. Le moteur de traduction applique uniquement les entiers positifs et traite les autres nombres comme si aucune limite n’était définie.
## 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.
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.