Accéder au contenu principal

Configuration

Champollion fonctionne sans configuration — il détecte automatiquement les fichiers de locale, le format et les langues cibles de votre projet. Pour plus de contrôle, créez champollion.config.json à la racine de votre projet, ou exécutez :

npx champollion init

Référence de configuration complète​

champollion.config.json
{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "contentDir": null,
  "translatableFields": null,
  "format": "auto",
  "model": "google/gemini-3.5-flash",
  "temperature": 0.3,
  "defaultMethod": "llm",
  "batchSize": 80,
  "coachingFile": null,
  "promptContext": null,
  "jsonConcurrency": 200,
  "contentConcurrency": 48,
  "fallbackPrefix": "[EN] ",
  "apiKeyEnvVar": "OPENROUTER_API_KEY",
  "baseUrl": "",
  "pairs": {},
  "languages": {},
  "lint": {
    "srcDir": null,
    "ignore": ["node_modules", ".next", "dist"],
    "minLength": 2
  },
  "seo": {
    "urlPattern": "/:locale/:path",
    "pages": null
  },
  "typegen": {
    "output": null,
    "autoGenerate": false
  }
}

:::note typegen n'est pas encore implémenté Le bloc de configuration typegen est reconnu et préservé par le chargeur de configuration, mais la génération de types TypeScript n'est pas encore implémentée. Ceci est un espace réservé pour une fonctionnalité prévue. La définition de ces valeurs n'a aucun effet. :::

Champs​

ChampTypeDéfautDescription
versionnumber3Version du schéma de configuration. Toujours 3.
inputLocalestring"en"Code de langue source (BCP 47).
localesDirstring"./locales"Chemin vers les fichiers de locale. Champollion analyse ce répertoire.
contentDirstringnullRépertoire de contenu Hugo. Active la traduction du corps Markdown.
translatableFieldsstring[]nullRemplace les champs frontmatter traduisibles par défaut pour la traduction de contenu. null utilise les valeurs par défaut intégrées (title, description, summary).
formatstring"auto"Format de fichier : json, toml, yaml, ou auto (détection à partir de l'extension).
modelstring"google/gemini-3.5-flash"Modèle par défaut pour les méthodes LLM. Accepte les slugs OpenRouter complets (provider/model) ou les alias courts de shared/model-aliases.json (par ex., gemini-flash). Les fournisseurs directs utilisent des noms simples (par ex., gpt-4o).
temperaturenumber0.3Température LLM (0,0–2,0). Plus bas = plus déterministe.
defaultMethodstring"llm"Méthode de traduction par défaut : llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api. Remplacée par le drapeau CLI --method.
batchSizenumber80Clés par lot de traduction. Plus élevé = moins d'appels API, mais des invites plus grandes.
coachingFilestringnullChemin vers un fichier d'invite de coaching en texte libre (relatif à la racine du projet). Le contenu est lu au démarrage et injecté dans l'invite système en tant que bloc Coaching guidance:.
promptContextstringnullChaîne de contexte d'application injectée dans l'invite système (par ex., « Descriptions de produits de commerce électronique »). Aide le modèle à adapter les traductions à votre domaine.
jsonConcurrencynumber200Traductions de locale parallèles maximales pour la synchronisation des clés JSON. Remplacée par le drapeau CLI --json-concurrency.
contentConcurrencynumber48Appels API parallèles maximaux pour la traduction de contenu (Markdown/MDX). Remplacée par le drapeau CLI --content-concurrency.
fallbackPrefixstring"[EN] "Préfixe de marqueur utilisé par audit et verify pour détecter les valeurs non traduites héritées des exécutions antérieures. Champollion n'écrit pas ce préfixe — il le lit uniquement pour la détection.
apiKeyEnvVarstring"OPENROUTER_API_KEY"Nom de la variable d'environnement pour la clé API. À remplacer pour les noms de variables d'environnement personnalisés.
baseUrlstring""URL de base pour la génération d'artefacts SEO (hreflang, sitemaps, JSON-LD).
pairsobject{}Remplacements de méthode, modèle et qualité par paire. Voir Configuration par paire.
languagesobject{}Remplacements par langue. Voir Configuration par langue.
lint.srcDirstringnullRépertoire source pour l'analyse lint. null = détection automatique à partir du framework.
lint.ignorestring[]["node_modules", ...]Motifs glob à exclure de l'analyse lint.
lint.minLengthnumber2Longueur minimale de chaîne à signaler comme codée en dur.
seo.urlPatternstring"/:locale/:path"Modèle de motif d'URL pour la génération de balises hreflang.
seo.pagesstring[]nullListe de pages explicite pour le SEO. null = détection automatique à partir des clés de locale.
typegen.outputstringnullChemin de sortie pour les types TypeScript générés. null = désactivé.
typegen.autoGeneratebooleanfalseRégénérer automatiquement les types après chaque synchronisation.

Configuration par paire​

Chaque paire source→cible peut être configurée indépendamment :

{
  "pairs": {
    "en:fr": {
      "method": "google-translate",
      "qualityTier": "high"
    },
    "en:ja": {
      "method": "llm",
      "model": "google/gemini-2.5-pro"
    },
    "en:crk": {
      "methodPlugin": "crk-coached-v1"
    }
  }
}

Champs de paire​

ChampTypeDescription
methodstringMéthode de traduction : llm, llm-coached, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini, api
methodPluginstringNom d'un plugin installé (de .champollion/methods/)
modelstringRemplace le modèle par défaut pour cette paire
temperaturenumberRemplace la température par défaut pour cette paire
batchSizenumberRemplace la taille de lot par défaut pour cette paire
registerstringRemplacement de registre/ton (clé prédéfinie ou texte libre)
endpointstringURL du point de terminaison API distant. Requis quand method est api.
coachingFilestringChemin vers un fichier d'invite de coaching pour cette paire
promptContextstringContexte d'application pour cette paire
qualityTierstringNiveau d'affichage : standard, high, research, verified

Configuration par langue​

Les langues acceptent trois formats :

Tableau de codes (le plus simple)​

{
  "languages": ["fr", "de", "ja"]
}

Chaque langue obtient son registre par défaut à partir du tableau de registres intégré. Les langues sans défaut obtiennent "Professional register.".

Objet avec chaînes de registre​

La valeur peut être une clé prédéfinie de la carte de la langue, ou du texte de registre personnalisé :

{
  "languages": {
    "fr": "casual-tu",
    "ko": "formal-hapsyo",
    "ja": "Custom: Polite Japanese for a gaming app."
  }
}

Champollion vérifie si la chaîne correspond à une clé prédéfinie dans la carte de la langue. Si c'est le cas, l'invite de registre complète de la carte est utilisée. Sinon, la chaîne est utilisée telle quelle. Voir Langues prises en charge pour les prédéfinitions disponibles.

Objet avec configuration complète​

{
  "languages": {
    "crk": {
      "name": "Plains Cree",
      "register": "SRO syllabics with grammatical precision.",
      "model": "google/gemini-2.5-pro",
      "batchSize": 5,
      "maxRetries": 5,
      "script": "cans"
    }
  }
}

Vous pouvez mélanger les objets raccourcis et complets dans le même bloc.

Champs de langue​

ChampTypeDescription
registerstringInstructions de style/ton. Peut être une clé prédéfinie (par ex., casual-tu, formal-hapsyo) ou du texte personnalisé. Voir Cartes de langue.
namestringNom de langue lisible par l'homme (pour l'affichage du statut)
modelstringRemplace le modèle par défaut
temperaturenumberRemplace la température par défaut
batchSizenumberRemplace la taille de lot par défaut
coachingFilestringChemin vers un fichier d'invite de coaching pour cette langue
promptContextstringContexte d'application pour cette langue
maxRetriesnumberBudget de tentatives maximal pour les lots échoués (défaut : 3)
scriptstringCode de script ISO 15924. Déclenche la validation de script dans la porte de qualité.

:::info Chaîne d'héritage Les paramètres se résolvent dans cet ordre (le premier gagne) :

niveau de paire → niveau de langue → configuration globale → valeurs par défaut

Par exemple, si pairs["en:fr"] définit model, cela remplace à la fois les valeurs model au niveau de la langue et au niveau global. :::

Source non-anglaise​

Si votre langue source n'est pas l'anglais :

# CLI flag (one-time)
npx champollion sync --source fr
champollion.config.json (permanent)
{
  "inputLocale": "fr"
}

Fichier de verrouillage​

Champollion crée .champollion.lock pour suivre les hachages SHA-256 des valeurs source traduites. Validez ce fichier afin que tous les développeurs partagent la même base de traduction.

Quand une valeur source change, le hachage ne correspond plus, et champollion retraduit cette clé lors de la prochaine synchronisation.

.champollionignore​

Créez .champollionignore à la racine de votre projet pour exclure les fichiers de l'analyse lint. Utilise des motifs glob, comme .gitignore :

.champollionignore
src/components/legacy/**
src/utils/constants.js
**/*.test.js

Répertoire .champollion/​

Champollion crée un répertoire .champollion/ à la racine de votre projet pour l'état interne. Vous devriez généralement l'ajouter à .gitignore — c'est une optimisation locale, pas une source de projet :

.champollion/
FichierObjectifValider ?
tm.jsonCache de mémoire de traduction — stocke les traductions précédentes indexées par texte source + locale + méthodeNon (cache local)
xliff/*.xliffFichiers d'export XLIFF pour examen par traducteur professionnelNon (transitoire)
methods/Manifestes de plugin de méthode installéeOui (configuration partagée)
backups/Sauvegardes pré-wrap (créées par wrap --undo)Non (filet de sécurité)

Voir Mémoire de traduction pour les détails sur tm.json et comment elle économise les coûts d'API.

API programmatique​

Pour les scripts de construction et les intégrations personnalisées, importez directement à partir du package :

import { GeminiMethod, runSync, resolveConfig } from 'champollion';

// Use a method class directly
const gemini = new GeminiMethod();
const result = await gemini.translate(
  ['greeting', 'farewell'],
  { greeting: 'Hello', farewell: 'Goodbye' },
  { target: 'fr', name: 'French', register: 'formal', model: 'gemini-2.5-flash' },
  { cwd: process.cwd() }
);
// result = { greeting: 'Bonjour', farewell: 'Au revoir' }

Exports disponibles​

ExportCe qu'il fait
TranslationMethodClasse de base pour toutes les méthodes
LLMMethodClasse de base pour les méthodes LLM (OpenRouter)
DirectLLMMethodClasse de base pour les fournisseurs LLM directs (OpenAI, Anthropic, Gemini)
OpenAIMethod, AnthropicMethod, GeminiMethodClasses de fournisseur LLM direct
DeepLMethod, MicrosoftTranslatorMethod, LibreTranslateMethodClasses de traduction automatique traditionnelle
GoogleTranslateMethodGoogle Cloud Translation
LLMCoachedMethodLLM coaché (OpenRouter + données de coaching)
APIMethodClient API distant
runSync, runContentSyncPipeline de synchronisation complète
resolveConfig, resolvePairsRésolution de configuration
validateTranslationsPorte de qualité
loadCoachingData, findDictionaryMatchesUtilitaires de coaching

Extension de fournisseur personnalisé​

Étendez DirectLLMMethod pour ajouter un nouveau fournisseur LLM en ~40 lignes :

import { DirectLLMMethod } from 'champollion';

class MistralMethod extends DirectLLMMethod {
  constructor(options) {
    super(options);
    this.name = 'mistral';
  }
  _getApiKeyEnvVar()     { return 'MISTRAL_API_KEY'; }
  _getApiKeyOptionsKey() { return 'mistralApiKey'; }
  _getDefaultModel()     { return 'mistral-large-latest'; }
  _getProviderLabel()    { return 'Mistral'; }

  _buildApiRequest({ prompt, systemMessage, apiKey, model, temperature }) {
    return {
      url: 'https://api.mistral.ai/v1/chat/completions',
      headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
      body: {
        model,
        messages: [
          ...(systemMessage ? [{ role: 'system', content: systemMessage }] : []),
          { role: 'user', content: prompt },
        ],
        temperature,
      },
    };
  }

  _extractResponseText(json) {
    return json.choices?.[0]?.message?.content;
  }

  // Optional but recommended: provider-specific setup help when translation fails
  getSetupHelp() {
    if (!process.env.MISTRAL_API_KEY) {
      return [
        '',
        '  ┌─ Missing API Key ─────────────────────────────────────────────┐',
        '  │ Mistral requires an API key from https://console.mistral.ai   │',
        '  │ Run: export MISTRAL_API_KEY=...                               │',
        '  └────────────────────────────────────────────────────────────────┘',
      ];
    }
    return ['        API key is set but translation failed. Check your Mistral dashboard.'];
  }
}

Vous obtenez gratuitement la traduction, le coaching, les boucles de tentatives, la validation de modèle, les niveaux de qualité et l'aide à la configuration. Seule la forme de la requête HTTP est spécifique au fournisseur. Pour les adaptateurs non-LLM qui utilisent fetch() brut, utilisez l'assistant fetchWithRetry() partagé de lib/methods/fetch-with-retry.js au lieu d'écrire votre propre boucle de tentatives.

Voir aussi​