Gabay para sa Agent: Paggamit ng champollion

Ang champollion ay isang CLI tool na nagsasalin ng mga locale file ng inyong app gamit ang isang command. Ang gabay na ito ay para sa mga AI agent (o mga developer na nagtatrabaho kasama ang mga AI agent) na nais mabilis na makapagsimula mula sa wala hanggang sa mga naisaling locale file.

:::tip Pamilyar na po ba kayo? Kung mga command lang ang kailangan ninyo, pumunta sa Sanggunian ng CLI. Kung nais ninyong bumuo at mag-benchmark ng translation method, tingnan ang Gabay para sa Arena Agent. :::

Pag-set up ng Environment

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

Mga kinakailangan:

Node.js 18+
Isang API key para sa inyong translation provider

Pag-set up ng API key — kailangan ng champollion ng kahit isang key depende sa mga method na ginagamit ninyo:

# 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

Awtomatikong binabasa ng Champollion ang .env. Kumuha ng OpenRouter key sa openrouter.ai/keys.

Unang Sync

Awtomatikong nade-detect ng Champollion ang inyong mga locale file, ang format ng mga ito (JSON, TOML, YAML, PO), at ang inyong mga target na wika:

npx champollion sync

Ano ang mangyayari:

Ilo-load ang champollion.config.json (o awtomatikong nade-detect ang mga setting)
I-scan ang source locale file, at i-flatten ang mga nested key
Ihahambing sa .champollion.lock (mga SHA-256 hash ng mga dating naisaling value)
Susuriin ang .champollion/tm.json para sa mga naka-cache na salin (Translation Memory)
Isasalin lamang ang mga nabago, nawawala, o stale na key gamit ang naka-configure na method
Patatakbuhin ang quality gate (5 pagsusuri) sa bawat salin
Isusulat ang mga pumapasang salin sa target locale file
Ia-update ang lock file at TM cache

Sa karaniwang muling pagpapatakbo pagkatapos baguhin ang isang key, ang step 4 ay naghahatid ng 142 key mula sa cache at ang step 5 ay nagsasalin ng 1 key. Ito ang dahilan kung bakit mabilis at mura ang mga kasunod na sync.

Configuration

Gumawa ng champollion.config.json sa project root ninyo:

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

Mahahalagang field:

Field	Layunin	Default
`inputLocale`	Source language	`en`
`pairs`	Map ng source→target na may method config	(kinakailangan)
`localesDir`	Kung saan matatagpuan ang mga locale file	(auto-detected)
`model`	LLM model para sa mga method na `llm`/`llm-coached`	`google/gemini-2.5-flash`
`batchSize`	Mga key kada API call	80 (LLM), 128 (Google)
`jsonConcurrency`	Parallel na locale translation para sa mga JSON key	200
`contentConcurrency`	Parallel na API call para sa content translation	48

Buong sanggunian: Configuration

Mga Translation Method

Method	Kailan gagamitin	Gastos	Kinakailangang API key
`llm`	Pangkalahatang gamit, mabuti para sa mga wikang may sapat na resource	Per-token (depende sa model)	`OPENROUTER_API_KEY`
`llm-coached`	Kapag mayroon kayong mga tuntunin sa grammar/dictionary para sa target na wika	Per-token + coaching context	`OPENROUTER_API_KEY`
`google-translate`	Mga high-resource na wika kung saan mahusay gumagana ang GT	$20/milyong character	`GOOGLE_TRANSLATE_API_KEY`
`api`	Custom pipeline na naka-host sa likod ng HTTP endpoint	Tinutukoy ng server	Wala (ang endpoint ang humahawak ng auth)
`plugin`	Pre-packaged method na naka-install nang lokal	Nag-iiba	Nag-iiba

Mga detalye: Mga Translation Method

Coaching Data

Para sa mga pair na llm-coached, ginagabayan ng coaching data ang LLM gamit ang tahasang kaalamang lingguwistiko. Gumawa ng coaching file:

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."
}

I-reference ito sa inyong pair config:

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

Tinitiyak ng quality gate na talagang lumalabas sa output ang mga termino sa dictionary — ang mga paglabag ay naka-log bilang mga babalang [TERM].

Mga detalye: Coaching Data

Quality Gate

Bawat salin ay dumaraan sa limang automated check bago ito isulat sa disk:

Check	Ano ang nahuhuli nito	Halimbawa
Empty/blank	Walang ibinalik ang model	`""`
Source echo	Ibinalik ng model ang English input nang hindi binago	`"Welcome"` para sa Japanese
Hallucination loop	Paulit-ulit na trigrams	`"Qo' Qo' Qo' Qo'"`
Length inflation	Ang output ay 4×+ na mas mahaba kaysa sa source	10-character na source → 50-character na output
Script compliance	Maling script para sa locale	Latin text para sa Arabic locale

Ang mga failure ay naka-log gamit ang prefix na [GATE]. Walang tahimik na fallback — kung nabigo ang isang salin, iniuulat ito, hindi tahimik na tinatanggap.

Mga detalye: Quality Gate

Translation Memory

Ini-cache ng Champollion ang mga salin sa .champollion/tm.json, na naka-key ayon sa source text + locale + method. Sa mga kasunod na sync, ang mga hindi nabagong key ay ihahatid mula sa cache — walang API call, walang gastos.

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

Para i-bypass ang cache para sa isang run: npx champollion sync --no-tm

Mga detalye: Translation Memory

Mga Generated File

Gumagawa ang Champollion ng ilang file sa inyong project. Alamin kung ano ang mga ito upang hindi ninyo aksidenteng mabura o ma-commit ang maling mga file:

File	Layunin	Git?
`.champollion.lock`	Mga SHA-256 hash ng mga naisaling source value (change detection)	Oo — i-commit ito
`.champollion-content.lock`	Pareho, ngunit para sa mga Markdown/MDX content file	Oo — i-commit ito
`.champollion/tm.json`	Translation Memory cache	Oo — i-commit ito (nakakatipid sa API costs para sa team)
`.champollion/coaching/`	Directory ng coaching data	Oo — ito ang inyong kaalamang lingguwistiko
`champollion.config.json`	Project configuration	Oo — i-commit ito

Mga Karaniwang Pattern

Isalin ang isang language pair:

npx champollion sync --pair en-fr

Isalin ang lahat ng naka-configure na pair:

npx champollion sync

Isinasalin ng Champollion ang lahat ng locale nang parallel. Sa TM caching, tanging mga nabagong key lamang ang tumatama sa API.

Content mode (Markdown/MDX para sa Docusaurus, Hugo, atbp.):

npx champollion sync --content

Isinasalin ang docs, blog post, at content file kasabay ng locale JSON. Gumagamit ng parallel concurrency (default: 48 sabay-sabay na API call). I-tune gamit ang --content-concurrency.

Dry run (preview nang hindi nagsusulat):

npx champollion sync --dry-run

Pilitin ang muling pagsasalin ng mga partikular na key:

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

Pilitin ang muling pagsasalin ng lahat ng content file:

npx champollion sync --force-content

Suriin ang status ng salin:

npx champollion status

Ipinapakita ang coverage, quality tiers, at plugin info para sa bawat pair.

I-audit para sa mga hindi naisaling fallback:

npx champollion audit

Inililista ang lahat ng fallback value na [EN] na kailangang isalin.

Pag-troubleshoot

Problema	Ayos
`OPENROUTER_API_KEY not set`	I-export ang key o idagdag ito sa `.env` sa inyong project root
`No locale files found`	Itakda ang `localesDir` sa config, o tiyaking tumutugma ang inyong mga locale file sa karaniwang naming (`en.json`, `fr.json`)
`[GATE] Script compliance failed`	Nakakuha ang inyong target locale ng Latin text sa halip na inaasahang script — subukan ang ibang model o magdagdag ng coaching data
`[GATE] Source echo`	Ibinalik ng model ang English nang hindi binago — karaniwang naaayos ito ng coaching data o ibang model
Naka-cache ang lahat ng salin	Patakbuhin gamit ang `--no-tm` upang i-bypass ang cache, o `--force-keys` para sa mga partikular na key
Mga conflict sa lock file	Gumagamit ang `.champollion.lock` ng mga SHA-256 hash — ligtas lutasin ang mga merge conflict sa pamamagitan ng pagpapanatili ng alinmang bersyon, pagkatapos ay muling patakbuhin ang sync

Ano ang Susunod

Quick Start — buong walkthrough para makapagsimula
Sanggunian ng CLI — bawat command at flag
Paano Ito Gumagana — ipinaliwanag ang sync pipeline
Ang Eval Harness Bridge — kung paano kumokonekta ang champollion sa Arena
Nais ba ninyong bumuo ng sarili ninyong translation method? Tingnan ang Gabay para sa Arena Agent — bumuo ng method, patunayang gumagana ito, manalo ng mga premyo.

Pag-set up ng Environment​

Unang Sync​

Configuration​

Mga Translation Method​

Coaching Data​

Quality Gate​

Translation Memory​

Mga Generated File​

Mga Karaniwang Pattern​

Pag-troubleshoot​

Ano ang Susunod​