에이전트 가이드: champollion 사용하기

champollion은 명령어 하나로 앱의 로케일 파일을 번역해 주는 CLI 도구예요. 이 가이드는 처음부터 빠르게 번역된 로케일 파일을 얻고자 하는 AI 에이전트(또는 AI 에이전트와 함께 작업하는 개발자)를 위한 것이에요.

:::tip 이미 익숙하신가요? 명령어만 필요하다면 CLI Reference로 바로 이동하세요. 번역 방식을 구축하고 벤치마킹하고 싶다면 Arena Agent Guide를 참고하세요. :::

환경 설정

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

요구 사항:

Node.js 18+
번역 제공자의 API 키

API 키 설정 — champollion은 사용하는 방식에 따라 최소 하나의 키가 필요해요:

# 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은 .env을 자동으로 읽어요. OpenRouter 키는 openrouter.ai/keys에서 발급받을 수 있어요.

첫 동기화

Champollion은 로케일 파일, 그 형식(JSON, TOML, YAML, PO), 그리고 대상 언어를 자동으로 감지해요:

npx champollion sync

동작 과정:

champollion.config.json을 로드해요 (또는 설정을 자동 감지해요)
소스 로케일 파일을 스캔하고 중첩된 키를 평탄화해요
.champollion.lock(이전에 번역된 값들의 SHA-256 해시)과 비교해요
.champollion/tm.json에서 캐시된 번역을 확인해요 (Translation Memory)
설정된 방식을 통해 변경되거나, 누락되거나, 오래된 키만 번역해요
모든 번역에 대해 품질 게이트(5가지 검사)를 실행해요
통과한 번역을 대상 로케일 파일에 작성해요
잠금 파일과 TM 캐시를 업데이트해요

키 하나를 변경한 후의 일반적인 재실행에서는 4단계에서 142개 키가 캐시에서 제공되고 5단계에서 1개 키만 번역돼요. 이것이 이후 동기화가 빠르고 저렴한 이유예요.

설정

프로젝트 루트에 champollion.config.json을 생성하세요:

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

주요 필드:

필드	용도	기본값
`inputLocale`	소스 언어	`en`
`pairs`	방식 설정과 함께하는 소스→대상 매핑	(필수)
`localesDir`	로케일 파일이 위치하는 곳	(자동 감지)
`model`	`llm`/`llm-coached` 방식용 LLM 모델	`google/gemini-2.5-flash`
`batchSize`	API 호출당 키 수	80 (LLM), 128 (Google)
`jsonConcurrency`	JSON 키에 대한 병렬 로케일 번역	200
`contentConcurrency`	콘텐츠 번역을 위한 병렬 API 호출	48

전체 레퍼런스: Configuration

번역 방식

방식	사용 시점	비용	필요한 API 키
`llm`	범용, 자원이 풍부한 언어에 적합	토큰당 (모델에 따라 다름)	`OPENROUTER_API_KEY`
`llm-coached`	대상 언어에 대한 문법 규칙/사전이 있을 때	토큰당 + 코칭 컨텍스트	`OPENROUTER_API_KEY`
`google-translate`	GT가 잘 작동하는 고자원 언어	100만 자당 $20	`GOOGLE_TRANSLATE_API_KEY`
`api`	HTTP 엔드포인트 뒤에 호스팅된 커스텀 파이프라인	서버에서 결정	없음 (엔드포인트가 인증 처리)
`plugin`	로컬에 설치된 사전 패키지 방식	다양함	다양함

세부 사항: Translation Methods

코칭 데이터

llm-coached 쌍의 경우, 코칭 데이터는 명시적인 언어학적 지식으로 LLM을 안내해요. 코칭 파일을 생성하세요:

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

쌍 설정에서 참조하세요:

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

품질 게이트는 사전 용어가 실제로 출력에 나타나는지 검증해요 — 위반 사항은 [TERM] 경고로 기록돼요.

세부 사항: Coaching Data

품질 게이트

모든 번역은 디스크에 작성되기 전에 다섯 가지 자동 검사를 거쳐요:

검사	잡아내는 것	예시
빈 값/공백	모델이 아무것도 반환하지 않음	`""`
소스 에코	모델이 영어 입력을 변경 없이 반환함	일본어에 대해 `"Welcome"`
환각 루프	반복되는 trigram	`"Qo' Qo' Qo' Qo'"`
길이 팽창	출력이 소스보다 4배 이상 김	10자 소스 → 50자 출력
스크립트 준수	로케일에 맞지 않는 스크립트	아랍어 로케일에 라틴 텍스트

실패 사항은 [GATE] 접두사와 함께 기록돼요. 조용한 폴백은 없어요 — 번역이 실패하면 조용히 수용되는 것이 아니라 보고돼요.

세부 사항: Quality Gate

Translation Memory

Champollion은 소스 텍스트 + 로케일 + 방식을 키로 하여 .champollion/tm.json에 번역을 캐시해요. 이후 동기화에서는 변경되지 않은 키가 캐시에서 제공돼요 — API 호출도, 비용도 없어요.

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

한 번의 실행에서 캐시를 우회하려면: npx champollion sync --no-tm

세부 사항: Translation Memory

생성된 파일

Champollion은 프로젝트에 여러 파일을 생성해요. 실수로 잘못된 파일을 삭제하거나 커밋하지 않도록 각각이 무엇인지 알아두세요:

파일	용도	Git?
`.champollion.lock`	번역된 소스 값의 SHA-256 해시 (변경 감지)	예 — 커밋하세요
`.champollion-content.lock`	동일하지만 Markdown/MDX 콘텐츠 파일용	예 — 커밋하세요
`.champollion/tm.json`	Translation Memory 캐시	예 — 커밋하세요 (팀의 API 비용 절약)
`.champollion/coaching/`	코칭 데이터 디렉터리	예 — 이것이 당신의 언어학적 지식이에요
`champollion.config.json`	프로젝트 설정	예 — 커밋하세요

일반적인 패턴

한 언어 쌍 번역하기:

npx champollion sync --pair en-fr

설정된 모든 쌍 번역하기:

npx champollion sync

Champollion은 모든 로케일을 병렬로 번역해요. TM 캐싱으로 변경된 키만 API에 도달해요.

콘텐츠 모드 (Docusaurus, Hugo 등을 위한 Markdown/MDX):

npx champollion sync --content

로케일 JSON과 함께 문서, 블로그 게시물, 콘텐츠 파일을 번역해요. 병렬 동시성을 사용해요 (기본값: 48개 동시 API 호출). --content-concurrency로 조정하세요.

드라이 런 (작성 없이 미리보기):

npx champollion sync --dry-run

특정 키 강제 재번역:

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

모든 콘텐츠 파일 강제 재번역:

npx champollion sync --force-content

번역 상태 확인:

npx champollion status

각 쌍에 대한 커버리지, 품질 등급, 플러그인 정보를 보여줘요.

번역되지 않은 폴백 감사:

npx champollion audit

번역이 필요한 모든 [EN] 폴백 값을 나열해요.

문제 해결

문제	해결
`OPENROUTER_API_KEY not set`	키를 export 하거나 프로젝트 루트의 `.env`에 추가하세요
`No locale files found`	설정에서 `localesDir`을 설정하거나, 로케일 파일이 표준 명명 규칙(`en.json`, `fr.json`)에 맞는지 확인하세요
`[GATE] Script compliance failed`	대상 로케일이 예상한 스크립트 대신 라틴 텍스트를 받았어요 — 다른 모델을 시도하거나 코칭 데이터를 추가하세요
`[GATE] Source echo`	모델이 영어를 변경 없이 반환했어요 — 코칭 데이터나 다른 모델로 보통 해결돼요
모든 번역이 캐시됨	캐시를 우회하려면 `--no-tm`로 실행하거나, 특정 키의 경우 `--force-keys`으로 실행하세요
잠금 파일 충돌	`.champollion.lock`은 SHA-256 해시를 사용해요 — 병합 충돌은 어느 버전이든 유지한 후 동기화를 다시 실행하여 안전하게 해결할 수 있어요

다음 단계

Quick Start — 전체 시작 가이드 안내
CLI Reference — 모든 명령어와 플래그
How It Works — 동기화 파이프라인 설명
The Eval Harness Bridge — champollion이 Arena에 연결되는 방식
자신만의 번역 방식을 구축하고 싶으신가요? Arena Agent Guide를 참고하세요 — 방식을 구축하고, 작동을 증명하고, 상을 받으세요.

환경 설정​

첫 동기화​

설정​

번역 방식​

코칭 데이터​

품질 게이트​

Translation Memory​

생성된 파일​

일반적인 패턴​

문제 해결​

다음 단계​