Guide d'agent : Utiliser champollion
champollion est un outil CLI qui traduit les fichiers de paramètres régionaux de votre application en une seule commande. Ce guide s'adresse aux agents IA (ou aux développeurs travaillant avec des agents IA) qui souhaitent passer de zéro à des fichiers de paramètres régionaux traduits rapidement.
:::tip Déjà familiarisé ? Si vous avez simplement besoin de commandes, accédez à la Référence CLI. Si vous souhaitez construire et évaluer une méthode de traduction, consultez le Guide d'agent Arena. :::
Configuration de l'environnement
# No global install needed — npx runs it directly
npx champollion sync
Prérequis :
- Node.js 18+
- Une clé API pour votre fournisseur de traduction
Configuration de la clé API — champollion a besoin d'au moins une clé selon les méthodes que vous utilisez :
# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..." # for llm / llm-coached methods
export GOOGLE_TRANSLATE_API_KEY="AIza..." # for google-translate method
# Option 2: .env file in your project root (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env
Champollion lit .env automatiquement. Obtenez une clé OpenRouter sur openrouter.ai/keys.
Première synchronisation
Champollion détecte automatiquement vos fichiers de paramètres régionaux, leur format (JSON, TOML, YAML, PO) et vos langues cibles :
npx champollion sync
Ce qui se passe :
- Charge
champollion.config.json(ou détecte automatiquement les paramètres) - Analyse votre fichier de paramètres régionaux source, aplatit les clés imbriquées
- Compare par rapport à
.champollion.lock(hachages SHA-256 des valeurs précédemment traduites) - Vérifie
.champollion/tm.jsonpour les traductions en cache (Mémoire de traduction) - Traduit uniquement les clés modifiées, manquantes ou obsolètes via la méthode configurée
- Exécute la porte de qualité (5 vérifications) sur chaque traduction
- Écrit les traductions réussies dans le fichier de paramètres régionaux cible
- Met à jour le fichier de verrouillage et le cache TM
Lors d'une réexécution typique après modification d'une clé, l'étape 4 sert 142 clés à partir du cache et l'étape 5 traduit 1 clé. C'est pourquoi les synchronisations ultérieures sont rapides et peu coûteuses.
Configuration
Créez champollion.config.json à la racine de votre projet :
{
"inputLocale": "en",
"pairs": {
"en-fr": { "method": "llm-coached" },
"en-ja": { "method": "google-translate" },
"en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
}
}
Champs clés :
| Champ | Objectif | Défaut |
|---|---|---|
inputLocale | Langue source | en |
pairs | Mappage source→cible avec configuration de méthode | (obligatoire) |
localesDir | Où se trouvent les fichiers de paramètres régionaux | (détection automatique) |
model | Modèle LLM pour les méthodes llm/llm-coached | google/gemini-2.5-flash |
batchSize | Clés par appel API | 80 (LLM), 128 (Google) |
jsonConcurrency | Traductions parallèles de paramètres régionaux pour les clés JSON | 200 |
contentConcurrency | Appels API parallèles pour la traduction de contenu | 48 |
Référence complète : Configuration
Méthodes de traduction
| Méthode | Quand l'utiliser | Coût | Clé API nécessaire |
|---|---|---|---|
llm | Usage général, bon pour les langues bien dotées en ressources | Par jeton (dépend du modèle) | OPENROUTER_API_KEY |
llm-coached | Quand vous avez des règles de grammaire/dictionnaire pour la langue cible | Par jeton + contexte de coaching | OPENROUTER_API_KEY |
google-translate | Langues à ressources élevées où la traduction automatique fonctionne bien | 20 $/million de caractères | GOOGLE_TRANSLATE_API_KEY |
api | Pipeline personnalisé hébergé derrière un point de terminaison HTTP | Déterminé par le serveur | Aucune (le point de terminaison gère l'authentification) |
plugin | Méthode pré-packagée installée localement | Varie | Varie |
Détails : Méthodes de traduction
Données de coaching
Pour les paires llm-coached, les données de coaching orientent le LLM avec des connaissances linguistiques explicites. Créez un fichier de coaching :
{
"grammar_rules": [
"Use formal register (vous) for all UI text",
"Adjectives agree in gender and number with the noun"
],
"dictionary": {
"dashboard": "tableau de bord",
"settings": "paramètres"
},
"style_notes": "Prefer active voice. Avoid anglicisms."
}
Référencez-le dans votre configuration de paire :
"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }
La porte de qualité vérifie que les termes du dictionnaire apparaissent réellement dans la sortie — les violations sont enregistrées comme des avertissements [TERM].
Détails : Données de coaching
Porte de qualité
Chaque traduction passe par cinq vérifications automatisées avant d'être écrite sur le disque :
| Vérification | Ce qu'elle détecte | Exemple |
|---|---|---|
| Vide/blanc | Le modèle n'a rien retourné | "" |
| Écho source | Le modèle a retourné l'entrée anglaise inchangée | "Welcome" pour le japonais |
| Boucle d'hallucination | Trigrammes répétés | "Qo' Qo' Qo' Qo'" |
| Inflation de longueur | La sortie est 4 fois ou plus plus longue que la source | Source de 10 caractères → sortie de 50 caractères |
| Conformité du script | Mauvais script pour la locale | Texte latin pour la locale arabe |
Les défaillances sont enregistrées avec le préfixe [GATE]. Pas de replis silencieux — si une traduction échoue, elle est signalée, pas silencieusement acceptée.
Détails : Porte de qualité
Mémoire de traduction
Champollion met en cache les traductions dans .champollion/tm.json, indexées par texte source + locale + méthode. Lors des synchronisations ultérieures, les clés inchangées sont servies à partir du cache — pas d'appel API, pas de coût.
[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]
Pour contourner le cache pour une exécution : npx champollion sync --no-tm
Détails : Mémoire de traduction
Fichiers générés
Champollion crée plusieurs fichiers dans votre projet. Sachez ce qu'ils sont pour ne pas supprimer ou valider accidentellement les mauvais :
| Fichier | Objectif | Git ? |
|---|---|---|
.champollion.lock | Hachages SHA-256 des valeurs source traduites (détection des modifications) | Oui — validez ceci |
.champollion-content.lock | Identique, mais pour les fichiers de contenu Markdown/MDX | Oui — validez ceci |
.champollion/tm.json | Cache de mémoire de traduction | Oui — validez ceci (économise les coûts API pour l'équipe) |
.champollion/coaching/ | Répertoire de données de coaching | Oui — c'est votre connaissance linguistique |
champollion.config.json | Configuration du projet | Oui — validez ceci |
Modèles courants
Traduire une paire de langues :
npx champollion sync --pair en-fr
Traduire toutes les paires configurées :
npx champollion sync
Champollion traduit toutes les locales en parallèle. Avec la mise en cache TM, seules les clés modifiées accèdent à l'API.
Mode contenu (Markdown/MDX pour Docusaurus, Hugo, etc.) :
npx champollion sync --content
Traduit les documents, articles de blog et fichiers de contenu aux côtés du JSON de paramètres régionaux. Utilise la concurrence parallèle (par défaut : 48 appels API simultanés). Ajustez avec --content-concurrency.
Exécution à blanc (aperçu sans écriture) :
npx champollion sync --dry-run
Forcer la re-traduction de clés spécifiques :
npx champollion sync --force-keys "hero.title,nav.about"
Forcer la re-traduction de tous les fichiers de contenu :
npx champollion sync --force-content
Vérifier l'état de la traduction :
npx champollion status
Affiche la couverture, les niveaux de qualité et les informations de plugin pour chaque paire.
Audit pour les replis non traduits :
npx champollion audit
Liste toutes les valeurs de repli [EN] qui nécessitent une traduction.
Dépannage
| Problème | Solution |
|---|---|
OPENROUTER_API_KEY not set | Exportez la clé ou ajoutez-la à .env à la racine de votre projet |
No locale files found | Définissez localesDir dans la configuration, ou assurez-vous que vos fichiers de paramètres régionaux correspondent à la dénomination standard (en.json, fr.json) |
[GATE] Script compliance failed | Votre locale cible a reçu du texte latin au lieu du script attendu — essayez un modèle différent ou ajoutez des données de coaching |
[GATE] Source echo | Le modèle a retourné l'anglais inchangé — les données de coaching ou un modèle différent résolvent généralement ce problème |
| Toutes les traductions en cache | Exécutez avec --no-tm pour contourner le cache, ou --force-keys pour des clés spécifiques |
| Conflits de fichier de verrouillage | .champollion.lock utilise des hachages SHA-256 — les conflits de fusion sont sûrs à résoudre en conservant l'une ou l'autre version, puis en réexécutant la synchronisation |
Prochaines étapes
- Démarrage rapide — procédure complète de démarrage
- Référence CLI — chaque commande et drapeau
- Comment ça marche — le pipeline de synchronisation expliqué
- Le pont du harnais d'évaluation — comment champollion se connecte à l'Arena
- Vous voulez construire votre propre méthode de traduction ? Consultez le Guide d'agent Arena — construisez une méthode, prouvez qu'elle fonctionne, remportez des prix.