Naar hoofdinhoud gaan

Agentgids: champollion gebruiken

champollion is een CLI-tool die de localisatiebestanden van uw applicatie vertaalt met één opdracht. Deze gids is bedoeld voor AI-agents (of ontwikkelaars die met AI-agents werken) die snel van nul naar vertaalde localisatiebestanden willen gaan.

:::tip Al bekend? Als u alleen opdrachten nodig hebt, ga dan naar de CLI-referentie. Als u een vertaalmethode wilt bouwen en benchmarken, zie dan de Arena Agent Guide. :::

Omgevingsinstellingen​

# No global install needed — npx runs it directly
npx champollion sync

Vereisten:

  • Node.js 18+
  • Een API-sleutel voor uw vertaalprovider

API-sleutelinstellingen — champollion heeft minimaal één sleutel nodig, afhankelijk van welke methoden u gebruikt:

# 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 leest .env automatisch. Verkrijg een OpenRouter-sleutel via openrouter.ai/keys.

Eerste synchronisatie​

Champollion detecteert automatisch uw localisatiebestanden, hun indeling (JSON, TOML, YAML, PO) en uw doeltalen:

npx champollion sync

Wat er gebeurt:

  1. Laadt champollion.config.json (of detecteert instellingen automatisch)
  2. Scant uw bronlocalisatiebestand en maakt geneste sleutels plat
  3. Vergelijkt met .champollion.lock (SHA-256-hashes van eerder vertaalde waarden)
  4. Controleert .champollion/tm.json op gecachede vertalingen (vertaalgeheugen)
  5. Vertaalt alleen gewijzigde, ontbrekende of verouderde sleutels via de geconfigureerde methode
  6. Voert de kwaliteitscontrole (5 controles) uit op elke vertaling
  7. Schrijft geslaagde vertalingen naar het doellocalisatiebestand
  8. Werkt het vergrendelingsbestand en de TM-cache bij

Bij een typische heruitvoering na het wijzigen van één sleutel levert stap 4 142 sleutels uit de cache en vertaalt stap 5 slechts 1 sleutel. Dit is waarom opeenvolgende synchronisaties snel en goedkoop zijn.

Configuratie​

Maak champollion.config.json aan in de hoofdmap van uw project:

{
  "inputLocale": "en",
  "pairs": {
    "en-fr": { "method": "llm-coached" },
    "en-ja": { "method": "google-translate" },
    "en-crk": { "method": "api", "endpoint": "http://localhost:3000/translate" }
  }
}

Belangrijke velden:

VeldDoelStandaard
inputLocaleBrontaalen
pairsKoppeling van bron→doel met methodeconfiguratie(vereist)
localesDirLocatie van localisatiebestanden(automatisch gedetecteerd)
modelLLM-model voor llm/llm-coached-methodengoogle/gemini-2.5-flash
batchSizeSleutels per API-aanroep80 (LLM), 128 (Google)
jsonConcurrencyParallelle localisatievertalingen voor JSON-sleutels200
contentConcurrencyParallelle API-aanroepen voor inhoudsvertaling48

Volledige referentie: Configuratie

Vertaalmethoden​

MethodeWanneer te gebruikenKostenBenodigde API-sleutel
llmAlgemeen gebruik, geschikt voor goed ondersteunde talenPer token (modelafhankelijk)OPENROUTER_API_KEY
llm-coachedWanneer u grammaticaregels/woordenboek voor de doeltaal hebtPer token + coachingcontextOPENROUTER_API_KEY
google-translateTalen met veel bronmateriaal waarbij GT goed werkt$20/miljoen tekensGOOGLE_TRANSLATE_API_KEY
apiAangepaste pipeline achter een HTTP-eindpuntServerbepaaldGeen (eindpunt verwerkt authenticatie)
pluginVooraf verpakte methode die lokaal is geïnstalleerdVarieertVarieert

Details: Vertaalmethoden

Coachinggegevens​

Voor llm-coached-paren sturen coachinggegevens de LLM met expliciete taalkundige kennis. Maak een coachingbestand aan:

coaching/fr.json
{
  "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."
}

Verwijs ernaar in uw paarconfiguratie:

"en-fr": { "method": "llm-coached", "coachingFile": "coaching/fr.json" }

De kwaliteitscontrole verifieert dat woordenboektermen daadwerkelijk in de uitvoer voorkomen — overtredingen worden geregistreerd als [TERM]-waarschuwingen.

Details: Coachinggegevens

Kwaliteitscontrole​

Elke vertaling doorloopt vijf geautomatiseerde controles voordat deze naar schijf wordt geschreven:

ControleWat het detecteertVoorbeeld
Leeg/blancoModel heeft niets geretourneerd""
BronherhalingModel heeft de Engelse invoer ongewijzigd geretourneerd"Welcome" voor Japans
HallucinatielusHerhaalde trigrammen"Qo' Qo' Qo' Qo'"
Lengte-inflatieUitvoer is 4× of meer langer dan de bron10-teken bron → 50-teken uitvoer
ScriptconformiteitVerkeerd schrift voor de taalinstellingLatijnse tekst voor Arabische taalinstelling

Fouten worden geregistreerd met het voorvoegsel [GATE]. Geen stille terugvalmechanismen — als een vertaling mislukt, wordt dit gerapporteerd en niet stilzwijgend geaccepteerd.

Details: Kwaliteitscontrole

Vertaalgeheugen​

Champollion slaat vertalingen op in .champollion/tm.json, geïndexeerd op brontekst + taalinstelling + methode. Bij opeenvolgende synchronisaties worden ongewijzigde sleutels uit de cache geleverd — geen API-aanroep, geen kosten.

[TM] 142 key(s) served from cache
Translating 3 key(s) to French (llm)... [OK]

Om de cache voor één uitvoering te omzeilen: npx champollion sync --no-tm

Details: Vertaalgeheugen

Gegenereerde bestanden​

Champollion maakt verschillende bestanden aan in uw project. Zorg dat u weet wat ze zijn, zodat u niet per ongeluk de verkeerde verwijdert of vastlegt:

BestandDoelGit?
.champollion.lockSHA-256-hashes van vertaalde bronwaarden (wijzigingsdetectie)Ja — vastleggen
.champollion-content.lockHetzelfde, maar voor Markdown/MDX-inhoudsbestandenJa — vastleggen
.champollion/tm.jsonVertaalgeheugencacheJa — vastleggen (bespaart API-kosten voor het team)
.champollion/coaching/Map met coachinggegevensJa — dit is uw taalkundige kennis
champollion.config.jsonProjectconfiguratieJa — vastleggen

Veelvoorkomende patronen​

Één taalpaar vertalen:

npx champollion sync --pair en-fr

Alle geconfigureerde paren vertalen:

npx champollion sync

Champollion vertaalt alle taalinstellingen parallel. Met TM-caching bereiken alleen gewijzigde sleutels de API.

Inhoudsmodus (Markdown/MDX voor Docusaurus, Hugo, enz.):

npx champollion sync --content

Vertaalt documentatie, blogberichten en inhoudsbestanden naast locale JSON. Maakt gebruik van parallelle gelijktijdigheid (standaard: 48 gelijktijdige API-aanroepen). Afstemmen met --content-concurrency.

Droge uitvoering (voorbeeld zonder schrijven):

npx champollion sync --dry-run

Specifieke sleutels geforceerd opnieuw vertalen:

npx champollion sync --force-keys "hero.title,nav.about"

Alle inhoudsbestanden geforceerd opnieuw vertalen:

npx champollion sync --force-content

Vertaalstatus controleren:

npx champollion status

Toont dekking, kwaliteitsniveaus en plug-ininformatie voor elk paar.

Controleren op onvertaalde terugvalwaarden:

npx champollion audit

Geeft alle [EN]-terugvalwaarden weer die vertaling vereisen.

Probleemoplossing​

ProbleemOplossing
OPENROUTER_API_KEY not setExporteer de sleutel of voeg deze toe aan .env in de hoofdmap van uw project
No locale files foundStel localesDir in de configuratie in, of zorg dat uw localisatiebestanden overeenkomen met de standaardnaamgeving (en.json, fr.json)
[GATE] Script compliance failedUw doeltaalinstelling heeft Latijnse tekst ontvangen in plaats van het verwachte schrift — probeer een ander model of voeg coachinggegevens toe
[GATE] Source echoHet model heeft het Engels ongewijzigd geretourneerd — coachinggegevens of een ander model lossen dit doorgaans op
Alle vertalingen gecachedVoer uit met --no-tm om de cache te omzeilen, of --force-keys voor specifieke sleutels
Conflicten in vergrendelingsbestand.champollion.lock gebruikt SHA-256-hashes — samenvoegconflicten kunnen veilig worden opgelost door een van beide versies te behouden en vervolgens de synchronisatie opnieuw uit te voeren

Volgende stappen​