Cookbook: 30개 언어 번역하기

프로젝트를 소수의 로케일에서 전 세계 범위로 확장하세요. 이 cookbook은 실제 다국어 배포를 위한 방법 선택, 비용 최적화, CI 통합을 단계별로 안내해요.

시나리오: en, fr, es를 갖춘 SaaS 앱이 있어요. 세 가지 품질 요구 사항 등급에 걸쳐 27개 언어를 추가해야 해요.

---

1단계: 언어 분류하기

30개 언어가 모두 같은 접근 방식이 필요한 것은 아니에요. 사용 가능한 방법의 품질에 따라 그룹으로 묶으세요:

등급	언어	방법	이유
Tier 1 — Premium	ja, ko, zh, de, pt	llm (GPT-4o)	고부가가치 시장, 미묘한 문법
Tier 2 — Standard	it, nl, pl, sv, da, fi, no, cs, ro, hu, el, tr, id, ms, th, vi, uk, bg	google-translate	대용량, Google의 우수한 지원
Tier 3 — Coached	crk, oj, mi, haw	llm-coached + 플러그인	저자원 언어, 용어 적용 필요

2단계: 쌍별 구성하기

champollion.config.json

{
  "version": 3,
  "inputLocale": "en",
  "localesDir": "./locales",
  "defaultMethod": "google-translate",
  "model": "google/gemini-3.5-flash",
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal" },
    "ko": { "name": "Korean", "register": "Formal" },
    "zh": { "name": "Simplified Chinese", "register": "Neutral" },
    "de": { "name": "German", "register": "Formal (Sie)" },
    "pt": { "name": "Brazilian Portuguese", "register": "Informal" },
    "crk": { "name": "Plains Cree (SRO)", "register": "Neutral" }
  },
  "pairs": {
    "en:ja": { "method": "llm", "model": "openai/gpt-4o" },
    "en:ko": { "method": "llm", "model": "openai/gpt-4o" },
    "en:zh": { "method": "llm", "model": "openai/gpt-4o" },
    "en:de": { "method": "llm", "model": "openai/gpt-4o" },
    "en:pt": { "method": "llm", "model": "openai/gpt-4o" },
    "en:crk": { "methodPlugin": "crk-coached-v1" }
  }
}

참고: pairs에 나열되지 않은 언어는 defaultMethod: "google-translate"를 상속해요. 30개 언어를 모두 나열할 필요는 없어요.

정보

crk 지원은 개발 중이에요 — 상태 및 기여 가이드라인은 저자원 언어 지원하기를 참고하세요.

3단계: API 키 설정하기

이 구성에는 두 개의 API 키가 모두 필요해요:

export OPENROUTER_API_KEY="sk-or-v1-..."
export GOOGLE_TRANSLATE_API_KEY="AIza..."

4단계: 먼저 Dry Run 실행하기

30개 언어를 번역하기 전에 항상 미리보기를 하세요:

npx champollion sync --dry

출력 결과를 검토하세요. 다음 내용이 표시돼요:

• 어떤 쌍이 어떤 방법을 사용하는지
• 로케일별로 새로 추가되거나 변경된 키가 몇 개인지
• 등급별 예상 API 호출 수

5단계: 동기화 실행하기

npx champollion sync

Champollion은 각 쌍을 독립적으로 처리해요. Google Translate를 사용하는 Tier 2 쌍은 빠를 거예요. Tier 1 LLM 쌍은 더 느리지만 품질이 더 높아요. Tier 3 coached 쌍은 플러그인의 코칭 데이터를 사용해요.

증분 업데이트

초기 동기화 이후, 이어지는 실행에서는 변경되거나 새로 추가된 키만 번역해요:

# Only keys that changed since last sync
npx champollion sync

lock 파일(.champollion.lock)이 번역된 내용을 추적하므로, 안정적인 콘텐츠를 다시 번역하는 일은 없어요.

6단계: 품질 감사하기

모든 언어 쌍의 상태를 확인하세요:

npx champollion status

각 쌍의 방법, 모델, 품질 등급, 그리고 코칭 데이터나 벤치마크 점수의 사용 가능 여부를 보여주는 표가 출력돼요.

출력 결과가 지정한 레지스터를 준수했나요?

2단계에서 언어별로 레지스터를 선언했어요 — 일본어에는 "Polite/formal", 독일어에는 "Formal (Sie)". (이 용어가 처음이신가요? 용어집에서 쉬운 말로 설명해드려요.) 이 지침들은 번역 프롬프트에 들어가지만, 프롬프트는 요청일 뿐 보장은 아니에요.

MT Eval Arena harness — 공개 리더보드를 구동하는 바로 그 도구 — 는 번역 샘플에서 레지스터 및 스타일 준수도를 측정할 수 있어요. 작문 스타일 지표는 각 출력 결과를 예상 레지스터(격식/비격식 표지, T–V 대명사, 축약형, 문장 길이 변동)와 비교하여 확인하고, 실행 전반에 걸친 style_consistency_rate를 보고해요. --style-profile을 사용하여 사용자 지정 브랜드 보이스 프로필을 지정할 수도 있어요.

# install the harness, then run your sample corpus through it
curl -fsSL champollion.dev/harness | bash
mt-eval run --corpus my-sample.json --style-profile brand-voice.json

솔직한 주의 사항 두 가지: 이 지표들은 정보 제공용이며(리더보드의 종합 점수에는 절대 반영되지 않아요), 격식 감지는 표지 기반이에요 — 사람의 판단이 아니라 변동 감지기예요. 자세한 내용과 지표 정의: 작문 스타일 및 레지스터 지표.

7단계: CI 통합

번역이 매 푸시마다 최신 상태를 유지하도록 GitHub Actions 워크플로에 추가하세요:

.github/workflows/i18n-sync.yml

name: Sync Translations
on:
  push:
    paths:
      - 'locales/en/**'

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Sync translations
        run: npx champollion sync
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
          GOOGLE_TRANSLATE_API_KEY: ${{ secrets.GOOGLE_TRANSLATE_API_KEY }}

      - name: Commit updated translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add locales/
          git diff --staged --quiet || git commit -m "chore(i18n): sync translations"
          git push

비용 추정

30개 언어에 걸쳐 500개의 소스 키가 있는 프로젝트의 경우:

등급	언어	방법	대략적인 비용
Tier 1 (5개 언어)	ja, ko, zh, de, pt	GPT-4o	전체 동기화당 약 $2.50
Tier 2 (18개 언어)	it, nl, pl 등	Google Translate	전체 동기화당 약 $0.90
Tier 3 (4개 언어)	crk, oj, mi, haw	GPT-4o-mini coached	전체 동기화당 약 $0.40
합계	30개 언어	혼합	전체 동기화당 약 $3.80

증분 동기화(변경된 키 5~20개)는 전체 동기화 비용의 일부에 불과해요.

함께 보기

• 번역 방법 — 각 번역 방법의 작동 원리와 사용 시점
• 플러그인 명세 — Tier 3 언어를 위한 코칭 데이터 생성하기
• CI/CD 가이드 — PR 미리보기 빌드를 포함한 고급 CI 패턴
• Quality Gate — Champollion이 모든 번역을 작성하기 전에 검증하는 방법
• 지원 언어 — 언어 코드 및 방법 호환성 전체 목록
• 작문 스타일 및 레지스터 지표 — eval harness로 레지스터/스타일 준수도 측정하기 (정보 제공용 지표)
• 용어집: 레지스터 — "레지스터"가 무엇을 의미하는지, 쉬운 말로
• 저자원 언어 지원하기 — 광범위한 MT 지원이 없는 언어를 위한 코칭 데이터 추가하기