CLI 레퍼런스
명령어
champollion init Interactive setup wizard (--yes for quick defaults)
champollion sync Translate & sync all locale files
champollion watch Auto-sync when the source file changes
champollion audit List all untranslated [EN] fallback values
champollion lint Scan source code for hardcoded strings
champollion wrap Auto-wrap hardcoded strings in t() calls (with undo)
champollion seo <sub> Generate hreflang, sitemap.xml, or JSON-LD schema
champollion integrity Audit locale files for format/encoding issues
champollion verify Verify translations are present and correct (CI gate)
champollion status Show pair configuration, plugins, and quality tiers
champollion provenance Audit translation resource licensing
champollion plugin <sub> Manage method plugins (install, remove, list)
champollion fonts <sub> Download web fonts for PUA script converters
champollion leaderboard Browse and install methods from the MT Eval Arena leaderboard
champollion tm <sub> Manage Translation Memory cache (stats, clear)
champollion xliff <sub> Export/import XLIFF 1.2 for professional review
특정 명령어에 대한 자세한 도움말은 champollion <command> --help을 실행하세요.
전역 옵션
--help, -h Show help (global or per-command)
--version, -v Print version and exit
--yes, -y Skip interactive prompts, use defaults
--config <path> Custom config file path
--dir <path> Override locales directory
--content-dir <path> Hugo/Docusaurus content directory for Markdown translation
--source <code> Override source locale (default: en)
--model <model> Override translation model (full slug or alias from shared/model-aliases.json)
--method <method> Translation method: llm, google-translate (default: from config)
--temperature <n> LLM temperature (0.0–2.0, default: 0.3)
--coaching-file <path> Path to free-text coaching prompt file (injected into system prompt)
--format <fmt> Locale file format: json, toml, yaml, or auto
--dry, --dry-run Preview changes without writing files
--concurrency <n> Max parallel API calls (sets both JSON and content, default: 48)
--json-concurrency <n> Max parallel locale translations for JSON keys (default: 200)
--content-concurrency <n> Max parallel API calls for content translation (default: 48)
--force-content Re-translate all content files (clears content lock)
--force-keys <keys> Comma-separated dot-notation keys to force re-translate
--no-tm Skip Translation Memory cache for this sync run
--no-verify Skip post-sync verification pass
--locale <code> Target locale (xliff export, tm clear)
--quiet Errors and warnings only — suppress banner, progress bar, and info lines
--json Machine-readable NDJSON output — one JSON object per event
init
champollion.config.json을 생성하는 대화형 설정 마법사예요. 소스 로케일, 대상 언어, 파일 형식, 번역 모델 설정을 안내해요.
champollion init # interactive wizard
champollion init --yes # skip wizard, use defaults
champollion init --yes --langs fr,de,ja # quick setup with specific languages
champollion init --source en --dir ./i18n # overrides with defaults
--langs 옵션: 쉼표로 구분된 대상 언어 코드 목록이에요. 언어 프롬프트를 건너뛰고 각 언어에 대한 기본 레지스터 프리셋을 적용해요. 완전한 비대화형 설정을 위해 --yes과 함께 사용하세요.
언어 프리셋: 대상 언어를 입력하라는 프롬프트가 나타나면 프리셋 이름을 입력할 수 있어요:
european→ fr, de, es, it, pt, nlasian→ ja, zh, koglobal→ fr, es, de, ja, zh, ko, pt, arnordic→ da, fi, nb, sv
프리셋과 개별 코드를 함께 사용할 수 있어요: european, ja → fr, de, es, it, pt, nl, ja
sync
모든 로케일 파일에서 누락되거나 오래된 키를 번역해요. 기본적으로 동기화 후 검증을 실행해요.
champollion sync # translate everything
champollion sync --dry-run # preview only
champollion sync --force-keys "hero.title" # force re-translate
champollion sync --force-keys "a.title,a.subtitle" # multiple keys
champollion sync --force-content # re-translate all Markdown/MDX
champollion sync --content-dir ./content # include Hugo Markdown
champollion sync --method google-translate # force Google Translate
champollion sync --concurrency 20 # 20 parallel API calls (both phases)
champollion sync --json-concurrency 30 # 30 parallel locale translations (JSON)
champollion sync --content-concurrency 8 # 8 parallel content translations
champollion sync --no-verify # skip post-sync verification
champollion sync --no-tm # skip cache, fresh API calls
Translation Memory: 기본적으로 sync은 .champollion/tm.json을 로드하고 변경되지 않은 소스 값에 대해 캐시된 번역을 제공해요. 캐시를 우회하려면 --no-tm을 사용하세요(번역 공급자를 변경하거나 품질을 디버깅할 때 유용해요). Translation Memory를 참조하세요.
변경 감지: champollion은 SHA-256 해시를 .champollion.lock에 저장해요. 소스 값이 변경되면 다음 동기화에서 해당 키를 자동으로 다시 번역해요. 모든 개발자가 기준선을 공유할 수 있도록 lock 파일을 커밋하세요.
병렬 처리: JSON 키 번역과 콘텐츠 번역 모두 병렬로 실행돼요. JSON 로케일은 동시에 번역되며(기본값: 200개의 동시 로케일), 각 로케일 내의 배치도 병렬화돼요(4개의 동시 배치). 콘텐츠 번역(Markdown, MDX, 블로그 게시물)은 평면 작업 항목 풀에서 실행돼요(기본값: 48개의 동시 API 호출). --json-concurrency, --content-concurrency 또는 --concurrency(둘 다 설정)로 재정의하세요.
출력: 동기화는 버전 배너, 형식/프레임워크 감지, 비용 추정치, 로케일별 진행 표시줄을 표시해요:
champollion v0.1.0
[INFO] Detected format: json (auto)
[INFO] Source: en.json (2,847 keys)
[INFO] Pairs: es-MX:llm, fr:deepl
[INFO] es-MX.json — 2,847 missing
████████████████████████████████ 2,847/2,847 keys
[INFO] fr.json — 2,847 missing
████████████████████████████████ 2,847/2,847 keys
[OK] Synced 5,694 keys total.
진행 표시줄은 각 배치(~80개 키) 이후 제자리에서 업데이트돼요. 오류/경고만 표시하려면 --quiet을, 기계 판독 가능한 NDJSON 출력을 위해서는 --json을 사용하세요. 둘 다 진행 표시줄과 배너를 억제해요.
watch
소스 로케일 파일이 변경되면 자동으로 동기화해요. Ctrl+C로 중단할 때까지 실행돼요.
champollion watch
audit
이전 실행에서 생성된 [EN] 접두사가 붙은 모든 미번역 대체 값을 나열해요. 발견되면 코드 1로 종료돼요 — 번역이 불완전한 빌드를 실패시키는 CI 게이트로 사용하세요.
champollion audit
verify
디스크에서 모든 로케일 파일을 다시 읽고 번역이 실제로 존재하며 올바른지 검증해요. 이는 (--no-verify이 전달되지 않는 한) 모든 sync 끝에서 자동으로 실행되는 것과 동일한 검증이에요.
champollion verify # verify all locale files
champollion verify --warn-only # non-blocking
champollion verify && echo "All good" # CI gate
검사하는 항목:
- 키 패리티 — 모든 소스 키가 각 대상에 존재하는지
- 이전 실행의
[EN]대체 마커 - 빈 번역
- 스크립트 준수 — 라틴 문자가 아닌 로케일은 ASCII가 아닌 번역을 가져야 함
- 플레이스홀더 보존 — ICU 플레이스홀더가 소스와 일치하는지
- 인코딩 문제 — BOM 마커, 보이지 않는 문자
- 소스 에코 — 소스와 동일한 값(경고)
lint
i18n 번역 호출을 사용해야 하는 하드코딩된 사용자 대상 문자열을 소스 코드에서 스캔해요. 프레임워크(next-intl, react-i18next, vue-i18n, Hugo)를 자동 감지해요.
champollion lint # exits 1 if issues found
champollion lint --warn-only # always exits 0
champollion lint --src ./app # custom source directory
champollion lint --min-length 4 # minimum string length to flag
감지하는 항목:
- JSX 텍스트,
placeholder,alt,aria-label,title의 하드코딩된 문자열 - 사용자 대상 콘텐츠는 있지만 i18n 프레임워크 임포트가 없는 파일
- 죽은 키 — 어떤 소스 파일도 참조하지 않는 로케일 키
- 커버리지 점수 — i18n을 거치는 문자열의 비율
제외: 프로젝트 루트에 .champollionignore을 생성하세요(.gitignore과 같은 glob 패턴).
wrap
lint이 감지한 하드코딩된 문자열을 t() 호출로 자동으로 감싸요. 파일을 수정하기 전에 자동 백업을 생성해요.
champollion wrap # auto-wrap with backup
champollion wrap --dry # preview wrapping changes
champollion wrap --undo # restore from .champollion-backup/
안전 게이트:
- Git 클린 검사(dry-run에서는 건너뜀)
.champollion-backup/으로 자동 백업- 각 파일 쓰기 전 diff 미리보기
- 백업에서 복원하는
--undo지원
seo
다국어 사이트용 SEO 아티팩트를 생성해요.
champollion seo hreflang # print hreflang tags
champollion seo sitemap --base-url https://example.com --out sitemap.xml
champollion seo jsonld --base-url https://example.com # JSON-LD schema
| 하위 명령어 | 출력 |
|---|---|
hreflang | <link rel="alternate" hreflang> 태그 |
sitemap | 다국어 sitemap.xml |
jsonld | JSON-LD WebSite 언어 스키마 |
integrity
번역된 로케일 파일의 손상 및 드리프트를 감지해요.
champollion integrity # exits 1 if issues found
champollion integrity --warn-only # non-blocking
검사하는 항목:
- 플레이스홀더 손상(예: 소스에는
{name}이 있지만 대상에는 누락됨) - 인코딩 문제(모지바케, 유효하지 않은 유니코드)
- 미번역 복사본(대상 값이 소스와 동일함)
- 고아 키(소스에 존재하지 않는 대상의 키)
- ICU MessageFormat 복수형 카테고리 완전성(예: 아랍어는 6개 카테고리 필요)
tm
Translation Memory 캐시(.champollion/tm.json)를 관리해요. TM은 이전 번역을 저장하고 후속 동기화에서 API를 호출하는 대신 이를 제공해요.
champollion tm stats # show cache statistics
champollion tm clear # clear cache (with confirmation)
champollion tm clear --yes # clear without confirmation
champollion tm clear --locale fr # clear only French entries
| 하위 명령어 | 출력 |
|---|---|
stats | 항목 수, 파일 크기, 로케일별 분석 |
clear | 캐시 파일 삭제(전체 또는 로케일별) |
| 옵션 | 효과 |
|---|---|
--locale <code> | 한 로케일의 항목만 지움 |
--yes | 확인 프롬프트 건너뛰기 |
TM의 작동 방식과 지워야 할 시기는 Translation Memory를 참조하세요.
xliff
전문 번역가 검토를 위해 XLIFF 1.2 파일을 내보내고 가져와요. XLIFF는 memoQ, SDL Trados, Phrase와 같은 CAT 도구에서 지원되는 범용 교환 형식이에요.
champollion xliff export --locale fr # export French XLIFF
champollion xliff export --locale ja --out ./review/ # custom output path
champollion xliff import .champollion/xliff/fr.xliff # import reviewed file
champollion xliff import ./reviewed.xliff --dry # preview import
| 하위 명령어 | 출력 |
|---|---|
export | 소스 + 대상 로케일 파일에서 .xliff 생성 |
import | 검토된 .xliff 번역을 로케일 파일에 병합 |
| 옵션 | 효과 |
|---|---|
--locale <code> | 내보내기용 대상 로케일(필수) |
--out <path> | 사용자 지정 출력 경로 또는 디렉터리 |
--dry | 쓰지 않고 가져오기 미리보기 |
전체 워크플로는 Working with Professional Translators를 참조하세요.
status
페어 구성, 설치된 플러그인, 품질 티어, 벤치마크 점수를 표시해요.
champollion status
provenance
설치된 모든 플러그인에 대한 번역 리소스 라이선스를 감사해요.
champollion provenance
plugin
번역 방법 플러그인을 관리해요. 플러그인은 .champollion/methods/에 설치되는 사전 패키지된 번역 레시피예요.
champollion plugin list # show installed plugins
champollion plugin install ./my-method/ # install from local directory
champollion plugin remove crk-coached-v1 # remove a plugin
플러그인 매니페스트 형식은 Plugin Specification을 참조하세요.
leaderboard
MT Eval Arena 리더보드에서 번역 방법을 탐색, 검색, 설치해요. 리더보드에서 설치한 방법은 벤치마크 점수와 함께 전체 표준 MethodConfig — 평가 중에 사용된 정확한 구성 — 를 함께 제공해요.
champollion leaderboard # show leaderboard
champollion leaderboard --pair en:fr # filter by language pair
champollion leaderboard --install crk-coached-v8 # install a method plugin
champollion leaderboard --install crk-coached-v8 --apply # install + patch config
| 옵션 | 효과 |
|---|---|
--pair <code> | 언어 페어로 리더보드 필터링(예: en:fr) |
--install <name> | 리더보드에서 방법 플러그인 설치 |
--apply | 설치 후 methodPlugin을 champollion.config.json에 자동으로 추가 |
--apply 워크플로: --apply로 설치하면 champollion은 방법 플러그인을 .champollion/methods/에 쓰고 또한 관련 페어에 사용하도록 champollion.config.json을 패치해요. 이것이 "무엇이 가장 좋은 점수를 받는가?"에서 "프로덕션에서 사용 중이다"로 가는 가장 빠른 경로예요.
fonts
인공어 스크립트 변환기용 PUA 웹 폰트를 다운로드하고 관리해요. Private Use Area 문자를 사용하는 언어(Klingon, Sindarin, Kryptonian)는 스크립트를 렌더링하기 위해 사용자 지정 웹 폰트가 필요해요. 이 명령어는 검증된 오픈 소스 저장소에서 폰트를 다운로드해요.
champollion fonts list # show needed fonts
champollion fonts install # download all needed fonts
champollion fonts install --css # also generate CSS snippet
champollion fonts install --dir ./public/fonts # custom output directory
| 하위 명령어 | 출력 |
|---|---|
list | 어떤 PUA 폰트가 필요한지와 설치 상태를 표시 |
install | 구성된 언어용 폰트 다운로드 |
| 옵션 | 효과 |
|---|---|
--dir <path> | 폰트 출력 디렉터리 재정의(프로젝트 유형에서 자동 감지) |
--css | 폰트와 함께 conlang-fonts.css 스니펫 생성 |
--config <path> | 구성 파일 경로(어떤 언어에 폰트가 필요한지 감지하는 데 사용) |
자동 감지: 출력 디렉터리는 프로젝트 구조에서 추론돼요:
- Docusaurus →
static/fonts/또는website/static/fonts/ - Hugo →
static/fonts/ - 기본값 →
public/fonts/
네이티브 유니코드 변환기(crk → Cree Syllabics, sr → Serbian Cyrillic)는 폰트 설치가 필요하지 않아요.
전체 PUA 폰트 세부 정보는 Conlangs, Scripts & Orthography를 참조하세요.
3계층 파이프라인
방탄 i18n을 위해 lint, sync, audit을 함께 사용하세요:
{
"scripts": {
"i18n:lint": "champollion lint",
"i18n:sync": "champollion sync",
"i18n:audit": "champollion audit"
}
}
| 계층 | 명령어 | 시점 | 목적 |
|---|---|---|---|
| Lint | lint | 커밋 전 | 하드코딩된 문자열이 있는 커밋 차단 |
| Sync | sync | 커밋 후 / CI | 누락되거나 변경된 키 번역 |
| Verify | verify | 동기화 후 / CI | 번역이 존재하며 올바른지 확인 |
| Audit | audit | 빌드 단계 | 로케일에 [EN] 마커가 있으면 배포 실패 |
참고
- Configuration — 구성 파일 레퍼런스
- Translation Methods — 페어별 방법 선택
- Translation Memory — 캐싱 및 비용 절감
- Working with Professional Translators — XLIFF 워크플로
- Plugin Specification — 플러그인 매니페스트 형식
- CI/CD Guide — 파이프라인에서 CLI 명령어 자동화
- How Sync Works — 동기화 파이프라인 이해
- Quality Gate — 번역이 검증되는 방식