Skip to content

Glossaire ​

Le glossaire assure une terminologie produit cohérente dans toutes les traductions. Les utilisateurs peuvent définir la traduction d'un terme dans une ou plusieurs langues, permettant au modèle d'IA d'utiliser cette traduction prédéfinie au lieu d'en choisir une lui-même. Il peut également être utilisé pour conserver certains termes, tels que les noms de produits, inchangés lors de la traduction dans d'autres langues.

Deux types d'indications sont envoyés au modèle :

  • Lignes de termes dans glossary.userGlossary (et, pour la documentation, le JSON et le SVG, les traductions d'interface utilisateur existantes de chaque bloc ui avec uiGlossary laissé activé). Une ligne n'est incluse que lorsque ce terme source apparaît dans le texte en cours de traduction.
  • Fichiers de contexte du projet dans glossary.contextFiles. Le brief complet est injecté dans chaque invite d'interface utilisateur, de documentation, de JSON, de SVG et de relecture. Cette section se trouve ci-dessous.

Fonctionnement du glossaire ​

D'où viennent les termes ​

SourceConfigurationUtilisé par
Catalogues d'interface utilisateurui[].uiGlossary (booléen, valeur par défaut true) — stringsJson de ce bloctranslate-docs, translate-json, translate-svg
CSV utilisateurglossary.userGlossarytranslate-ui, proofread-ui, translate-docs, translate-json, translate-svg

init pointe glossary.userGlossary vers glossary-user.csv et ne crée pas ce fichier. Exécutez glossary-generate lorsqu'il est manquant, et insérez-y les termes de domaine avant le premier translate-ui. Une deuxième traduction d'une chaîne inchangée peut revenir formulée différemment. Le glossaire est ce qui fait que les deux exécutions concordent.

Un bloc avec uiGlossary: true réutilise les traductions déjà stockées dans son strings.json comme suggestions, afin que la documentation, le JSON et le SVG restent alignés avec l'interface utilisateur. translate-ui et proofread-ui ne lisent pas ces catalogues — ils ne prennent que les suggestions du CSV utilisateur, de sorte qu'une mauvaise traduction d'interface n'est pas réinjectée comme terme préféré. Définissez uiGlossary sur false pour un bloc qui ne doit pas influencer les autres pipelines. Lorsque plusieurs blocs partagent un terme source, le premier bloc remplit une locale et les blocs suivants n'ajoutent que les locales encore manquantes. Le CSV utilisateur l'emporte sur tous les catalogues d'interface. Une ligne dont le locale est un code spécifique remplace à la fois la ligne * et la traduction du catalogue d'interface pour cette locale. Un locale de * applique la même traduction à chaque locale cible qui n'en possède pas déjà une provenant d'un catalogue d'interface.

Les abréviations compactes des libellés d'interface (un point final tel que Alm., ou une compression courte en un seul mot telle que Size → Tam) restent disponibles pour la traduction d'interface. Les prompts de documentation les ignorent, afin de ne pas pousser les modèles à inventer des jetons {{…}} dans le markdown ou le MDX.

Un préfixe de plusieurs mots partagé par deux ou plusieurs clés de catalogue est ajouté comme son propre terme lorsque ce préfixe n'est pas déjà une clé. Pour chaque locale, la traduction est le début partagé de ces traductions de catalogue, coupé à une limite de mot, et seulement lorsque ce début partagé fait au moins quatre caractères. Cursor Models run out et Cursor Models at renewal peuvent donner Cursor Models lorsque les deux chaînes allemandes commencent par Cursor-Modelle. Une ligne CSV utilisateur pour la même source remplace cette traduction pré-remplie.

Quand un terme est envoyé ​

La correspondance ne tient pas compte de la casse et s'arrête à une limite de mot (espace ou ponctuation). Les termes les plus longs sont privilégiés, et les correspondances qui se chevauchent sont écartées. Lorsqu'un terme correspond au lot en cours, le prompt reçoit une indication du type "dashboard" → "Tableau". Si cette ligne comporte une note de Contexte, la note est ajoutée uniquement pour cette correspondance.

Le Contexte est un guide d'utilisation dans la langue source (ce que le terme signifie ou comment l'utiliser). Ce n'est pas une traduction. La modification d'une note de Contexte, ou de tout contenu glossary.contextFiles, actualise les traductions mises en cache pour la locale concernée lors de la prochaine exécution — vous n'avez pas besoin de --force. La modification de la Traduction préférée uniquement sur une ligne qui n'est pas Forcer conserve le cache existant jusqu'à ce que vous passiez --force ou --force-update. Une ligne Forcer (nouvelle, modifiée ou effacée) invalide le cache uniquement pour les segments dont la source contient ce terme, et seulement lorsque le texte stocké n'inclut pas déjà la traduction forcée. Laissez le Contexte vide sur cette ligne pour cette actualisation ciblée ; une note de Contexte actualise toujours la locale entière. Les lignes que vous avez modifiées dans le tableau de bord restent comme user-edited.

La traduction Markdown vérifie une étiquette d'interface utilisateur de deux à cinq mots lorsque la source la cite comme l'intégralité d'une étendue en gras ou en code intégré, dans un titre, ou sur une ligne qui ne contient que cette étiquette. Une phrase en gras plus longue qui contient le terme est un indice, donc **Ask for target language** n'exige pas la forme de catalogue de Target language. Les indices d'un seul mot peuvent toujours être fléchis. Un indice CSV utilisateur qui n'est pas également une étiquette d'interface utilisateur reste un indice. La vérification ignore la casse et recherche le libellé du catalogue comme une sous-chaîne, de sorte qu'une forme fléchie peut toujours être manquée. Elle essaie le modèle suivant jusqu'à ce que la même erreur de qualité se soit produite trois fois ou que la liste des modèles soit épuisée, et elle ne divise pas le segment pour une étiquette manquante. Si ces tentatives ne manquent que cette vérification, l'exécution conserve la tentative avec le moins de manques, écrit le document et met en cache le segment avec un avertissement d'étiquette de glossaire. Le résumé liste ces avertissements, et cacheDir reçoit glossary-review-*.md, une invite que vous pouvez coller à une IA pour marquer chaque manque comme un faux positif ou un vrai manque. Le code de sortie reste 0 lorsque le seul problème est cet avertissement.

Un faux positif peut être ignoré avec glossary.labelCheckSkips dans la configuration du projet (l'onglet Glossaire du tableau de bord modifie la même liste). Chaque entrée nomme le term anglais, le locales à ignorer (* signifie toutes les locales) et des files globs facultatifs. Le terme reste une suggestion d'invite. --recheck-glossary-warnings traduit à nouveau les segments signalés et efface le signalement lorsque la vérification passe maintenant. --force les retraduit avec tous les autres segments. Le markdown mis en cache est revérifié lorsque le fichier est traité (--force-update) ; un fichier que le suivi des fichiers ignore est laissé tel quel jusqu'à ce qu'un terme Force dans ce fichier soit absent de la sortie, ou jusqu'à ce que --recheck-glossary-warnings ouvre un fichier qui contient un segment signalé. Une traduction de catalogue qui diffère de la source est requise partout où cette étiquette est citée, y compris un nom de produit traduit. Conservez l'orthographe source avec une ligne Force dont la traduction est égale à la source.

Force ​

Lorsque Force vaut true, yes ou 1, le terme source est retiré du texte avant que le modèle ne le voie, puis la traduction préférée est réinsérée ensuite. Le libellé est exact, et non une simple suggestion. Les mêmes règles de limite de mot et de correspondance la plus longue s'appliquent. Laissez Force vide (ou mettez false) lorsque le modèle doit privilégier la traduction mais peut néanmoins la fléchir.

Générer un glossaire ​

glossary-generate écrit un CSV vide avec l'en-tête standard. Il utilise glossary.userGlossary depuis la config, ou glossary-user.csv lorsque cette clé n'est pas définie. Il refuse d'écraser un fichier déjà existant (code de sortie 1).

bash
ai-i18n-tools glossary-generate
# or: ai-i18n-tools glossary-generate -o i18n/glossary.csv

Faites pointer la config vers le fichier :

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv"
  }
}

Vous pouvez également créer le fichier de glossaire CSV directement depuis le tableau de bord. La première action Ajouter de l'onglet Glossaire créera le fichier si glossary.userGlossary est spécifié et que le fichier n'existe pas déjà. Lorsque glossary.autoAddUserEditedToGlossary est défini sur true (la valeur par défaut), la correction d'une chaîne d'interface utilisateur dans le tableau de bord peut ajouter cette modification au CSV lors de la prochaine exécution de translate-ui. Le tableau de bord sert également d'éditeur pour le glossaire CSV, vous permettant d'ajouter, de modifier ou de filtrer des lignes directement dans l'interface.

Colonnes CSV ​

Ligne d'en-tête :

text
Original language string,locale,Translation,Force,Context

en ou English est accepté à la place de Original language string. Notes est accepté à la place de Context.

ColonneSignification
Chaîne dans la langue d’origineTerme ou expression source, dans la locale source
localeCode de la locale cible, ou * pour toutes les cibles
TraductionTraduction préférée
Forcetrue, yes ou 1 pour exiger ce libellé ; sinon, une suggestion
ContexteExplication facultative dans la langue source. Envoyée uniquement lorsque ce terme correspond

Exemples ​

Un terme produit pour chaque locale, un libellé allemand forcé, et une ligne française qui explique un mot que le modèle pourrait prendre au sens littéral :

csv
"Original language string","locale","Translation","Force","Context"
"dashboard","*","Tableau","false","The analytics home, not a vehicle panel"
"Save","de","Speichern","true",""
"workspace","fr","espace de travail","false","A user's project container, not an office"

Combiné à un brief de projet :

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"],
    "contextMaxChars": 12000
  }
}

Référence du champ : glossary dans Configuration. Référence de la commande : glossary-generate.

Fichiers de contexte de projet ​

glossary.contextFiles est destiné aux directives au niveau du produit qui n'appartiennent pas à une seule ligne CSV : ce qu'est le produit, à qui il est destiné, le ton et les termes faciles à mal traduire. Pointez la configuration vers un ou plusieurs fichiers .md / .txt relatifs au répertoire de travail ; ils sont concaténés dans l'ordre indiqué et injectés dans chaque invite d'interface utilisateur, de documentation, JSON, SVG et de relecture.

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md"]
  }
}

Rédigez le brief dans le paramètre régional source, maintenez-le bien en dessous de glossary.contextMaxChars (par défaut 12000), et stockez-le en dehors de docs[].contentPaths, sauf si vous souhaitez également que ce fichier soit traduit. Voir glossary dans Configuration.

Générer un fichier de contexte avec un agent IA ​

Demandez à un agent (Cursor, Claude Code, Copilot, et similaires) de lire le dépôt et de rédiger le brief. Collez une invite comme celle-ci :

text
Create a translation-context Markdown file for this repository at i18n/product-context.md.

This file is injected verbatim into every ai-i18n-tools translation prompt (UI strings, docs, JSON, SVG, proofread). It must stay in the source language of the project (do not translate it). Translators already receive a glossary of preferred term mappings; this file should explain meaning, audience, and register — not duplicate every glossary row.

Requirements:
- Concise: aim for 1–4 KB, hard limit 8000 characters. No full manuals, README dumps, or changelog history.
- Source-language only. Short headings, bullet lists, and a few example sentences are enough.
- No secrets, API keys, credentials, personal data, internal URLs, or unpublished commercial figures.
- Do not invent product facts. If something is unclear, omit it or mark it as unknown.
- Do not put this file under a path that is also listed in docs[].contentPaths.

Cover, in this order:
1. Product in one paragraph: what it is, who uses it, and the default tone (formal / informal / technical).
2. Domain and disambiguation: terms that look ordinary in English but have a product-specific meaning (for example “dashboard” as an analytics home, not a vehicle panel).
3. Features or areas that change register (billing vs. onboarding vs. admin).
4. Things translators must preserve exactly: brand names, CLI flags, config keys, code identifiers, placeholder tokens.
5. Locale notes only when they affect meaning for every target (for example “use formal you”). Do not list per-locale translations here.

Write only the Markdown file. Afterward, remind me to add it to glossary.contextFiles in ai-i18n-tools.config.json if it is not already listed.

Examinez le fichier avant la prochaine exécution de sync / translate-*. La modification du fichier invalide les traductions mises en cache pour chaque paramètre régional lors de cette exécution, alors maintenez le brief stable une fois que la qualité est bonne.

Publié sous licence MIT.