번역 방법
Champollion은 열 가지 번역 방법을 지원해요. 각 언어 쌍마다 서로 다른 방법을 사용할 수 있어요 — 프로젝트 전체에 하나의 접근 방식만 사용하도록 묶이지 않아요.
방법 비교
LLM 제공자
품질 중심, Markdown 인식, 코칭 호환. 콘텐츠가 많은 프로젝트에 가장 적합해요.
| 방법 | 키 | 기능 |
|---|---|---|
llm (기본값) | OPENROUTER_API_KEY | OpenRouter를 통한 LLM — 200개 이상의 모델, 자동 라우팅 |
llm-coached | OPENROUTER_API_KEY | LLM + 문법 규칙, 사전, 스타일 노트 |
openai | OPENAI_API_KEY | OpenAI API 직접 사용 (gpt-4o, gpt-4o-mini) |
anthropic | ANTHROPIC_API_KEY | Anthropic API 직접 사용 (Claude Sonnet, Haiku, Opus) |
gemini | GEMINI_API_KEY | Google Gemini API 직접 사용 (Flash, Pro) — 무료 등급 |
전통적 MT
속도와 비용 중심. 대량의 키-값 쌍에 가장 적합해요.
| 방법 | 키 | 기능 |
|---|---|---|
google-translate | GOOGLE_TRANSLATE_API_KEY | Google Cloud Translation API v2 (130개 이상의 언어) |
deepl | DEEPL_API_KEY | 용어집 지원이 포함된 DeepL API (30개 이상의 언어) |
microsoft-translator | MICROSOFT_TRANSLATOR_API_KEY | Azure Cognitive Services Translator (100개 이상의 언어) |
libretranslate | (self-hosted) | 자체 호스팅 LibreTranslate (AGPL, 무료) |
인프라
| 방법 | 키 | 기능 |
|---|---|---|
api | (per provider) | 모든 REST 번역 엔드포인트를 위한 경량 HTTP 클라이언트 |
의사 결정 트리
llm — LLM 번역 (기본값)
OpenRouter의 모든 LLM을 통해 번역해요. 이것이 기본 방법이며 가장 다재다능해요.
작동 방식:
- 레지스터 및 컨텍스트 지침과 함께 키를 배치 처리해요 (기본값 80개/배치)
- 구조화된 프롬프트로 OpenRouter에 전송해요
- JSON 응답을 파싱해요
- 품질 게이트를 통해 각 번역을 검증해요
- 통과한 번역을 작성하고, 실패한 것은 재시도하거나 거부해요
사용 시기: 대부분의 프로젝트. 특히 코드 블록과 단축 코드를 보호해야 하는 Markdown이 포함된 콘텐츠 중심 사이트에 적합해요.
구성:
{
"defaultMethod": "llm",
"model": "google/gemini-3.5-flash"
}
llm-coached — 코칭된 LLM 번역
llm와 동일하지만, 모든 프롬프트에 문법 규칙, 용어 사전, 스타일 노트가 주입돼요.
작동 방식:
.champollion/coaching/<locale>.json또는 플러그인의coaching/디렉터리에서 코칭 데이터를 로드해요- 시스템 프롬프트에 문법 규칙, 사전 용어, 스타일 노트를 주입해요
- 소스 키와 일치하는 사전 용어는 필수 용어로 포함돼요
llm와 마찬가지로 번역이 진행되며, 코칭 데이터가 정밀도를 더해줘요
사용 시기: 저자원 언어, 도메인별 용어(법률, 의료), 공식 레지스터, 또는 일반적인 LLM 출력이 충분히 정밀하지 않은 모든 경우예요.
코칭 데이터 형식:
{
"grammar_rules": [
"French adjectives agree in gender and number with the noun they modify",
"Use 'vous' for formal contexts, 'tu' for informal"
],
"dictionary": {
"dashboard": "tableau de bord",
"deployment": "déploiement",
"settings": "paramètres"
},
"style_notes": "Prefer active voice. Avoid anglicisms where a native French term exists."
}
참고: 저자원 언어 가이드
openai — OpenAI API 직접 사용
OpenAI Chat Completions API를 통해 직접 번역해요. OpenRouter 중개자 없이 — 본인의 키, 본인의 계정, 본인의 사용량 대시보드를 사용해요.
모델: gpt-4o (기본값), gpt-4o-mini
기능:
- ✅ Markdown 인식 (콘텐츠 번역)
- ✅ 코칭 지원 (문법 규칙, 사전 재정의, 스타일 노트)
- ✅ 구조화된 키-값 출력을 위한 JSON 모드
- ✅ 재시도 기능이 포함된 지수 백오프
구성:
{
"pairs": {
"en:fr": { "method": "openai", "model": "gpt-4o-mini" }
}
}
export OPENAI_API_KEY=sk-proj-...
platform.openai.com/api-keys에서 키를 받으세요.
anthropic — Anthropic API 직접 사용
Anthropic Messages API를 통해 직접 번역해요. 코칭 데이터에 system 매개변수를 사용하여 Anthropic의 프롬프트 캐싱을 활성화해요.
모델: claude-sonnet-4-6 (기본값), claude-haiku-4-5, claude-opus-4-7
기능:
- ✅ Markdown 인식 (콘텐츠 번역)
- ✅ 코칭 지원 (문법 규칙, 사전 재정의, 스타일 노트)
- ✅ 시스템 프롬프트 캐싱 (배치 전반에 걸쳐 코칭 비용을 분산함)
- ✅ 재시도 기능이 포함된 지수 백오프
구성:
{
"pairs": {
"en:ja": { "method": "anthropic", "model": "claude-haiku-4-5" }
}
}
export ANTHROPIC_API_KEY=sk-ant-...
console.anthropic.com에서 키를 받으세요.
gemini — Google Gemini API 직접 사용
Google Gemini generateContent API를 통해 직접 번역해요. 무료 등급 사용 가능 — 비용 없이 시작하기에 가장 좋은 방법이에요.
모델: gemini-2.5-flash (기본값), gemini-2.5-pro
기능:
- ✅ Markdown 인식 (콘텐츠 번역)
- ✅ 코칭 지원 (문법 규칙, 사전 재정의, 스타일 노트)
- ✅
responseMimeType를 통한 JSON 응답 모드 - ✅ 무료 등급 (넉넉한 일일 할당량)
- ✅ 재시도 기능이 포함된 지수 백오프
구성:
{
"pairs": {
"en:ko": { "method": "gemini", "model": "gemini-2.5-pro" }
}
}
export GEMINI_API_KEY=AI...
aistudio.google.com/apikey에서 키를 받으세요.
모델 검증
직접 LLM 제공자(openai, anthropic, gemini)는 첫 사용 시 모델 문자열을 검증해요. 이를 통해 세 가지 범주의 실수를 잡아내요:
잘못된 방법 형식 — 직접 제공자에 OpenRouter 스타일의 모델 경로를 사용하는 경우:
[WARN] OpenAI: model "google/gemini-3.5-flash" looks like an OpenRouter path.
Direct providers use bare model names (e.g., "gpt-4o").
To use OpenRouter models, set method to 'llm' instead.
잘못된 제공자 — 완전히 다른 제공자의 모델을 사용하는 경우:
[WARN] Gemini: model "claude-sonnet-4-6" is an Anthropic model.
This provider (gemini) cannot serve Anthropic models.
Use --method anthropic or set "method": "anthropic" in config.
더 이상 사용되지 않거나 철자가 틀린 모델 — 첫 API 호출 시, champollion은 제공자의 실시간 모델 목록을 가져와 본인의 모델을 그 목록과 대조해 확인해요:
[WARN] Gemini: model "gemini-1.5-flash" not found in available models.
Similar models: gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-pro
The API call will proceed — the provider will give the final verdict.
:::note 이것은 오류가 아니라 경고예요 모델 검증은 경고를 기록하지만 API 호출을 차단하지는 않아요. 제공자 API가 최종 판정을 내려요 — 향후 모델 이름이 다른 패턴과 일치할 수 있으므로, 휴리스틱으로 차단하고 싶지 않아요. :::
google-translate — Google Cloud Translation API
Google Cloud Translation API v2와의 직접 통합이에요. REST API를 사용해요 — SDK 없이, 서비스 계정 없이. API 키만 있으면 돼요.
사용 시기: 미묘함보다 속도와 비용이 더 중요한 대량의 키-값 문자열 쌍. 기본적으로 130개 이상의 언어를 지원해요.
제한 사항:
- ⚠️ Markdown 인식 없음. 코드 블록, 단축 코드, 보간 변수를 손상시켜요.
- 레지스터/톤 제어 없음
- 코칭 또는 용어 적용 없음
npx champollion sync --method google-translate
:::tip 자동 감지
GOOGLE_TRANSLATE_API_KEY만 설정되어 있고 OpenRouter 키가 없는 경우, champollion은 자동으로 Google Translate로 전환해요. 구성 변경이 필요하지 않아요.
:::
deepl — DeepL API
DeepL 번역 API와의 직접 통합이에요. 일관된 용어를 위한 용어집을 지원해요.
사용 시기: DeepL이 뛰어난 유럽 언어(독일어, 프랑스어, 스페인어, 네덜란드어, 폴란드어 등). 용어집 지원은 코칭 데이터 없이도 일관된 용어를 적용해줘요.
기능:
- ✅ 무료/프로 엔드포인트 자동 감지 (무료 키에
:fx접미사) - ✅ 용어집 생성 및 관리
- ✅ 격식 수준 제어
- ⚠️ Markdown 인식 없음 — 키-값 쌍만 지원
구성:
{
"pairs": {
"en:de": { "method": "deepl" }
}
}
export DEEPL_API_KEY=your-key-here
deepl.com/pro-api에서 키를 받으세요.
microsoft-translator — Azure Cognitive Services
Microsoft Translator Text API v3와의 직접 통합이에요.
사용 시기: 기존 Azure 인프라가 있는 엔터프라이즈 환경. Google Translate가 다루지 않는 많은 언어를 포함하여 100개 이상의 언어를 지원해요.
기능:
- ✅ 요청당 최대 100개 세그먼트 (높은 처리량)
- ✅ 지연 시간 최적화를 위한 선택적 지역 매개변수
- ⚠️ Markdown 인식 없음 — 키-값 쌍만 지원
- ⚠️ 콘텐츠 번역 없음 — 키-값 쌍만 지원
구성:
{
"pairs": {
"en:ar": { "method": "microsoft-translator" }
}
}
export MICROSOFT_TRANSLATOR_API_KEY=your-key
export MICROSOFT_TRANSLATOR_REGION=global # optional
Azure Portal → Cognitive Services → Translator에서 키를 받으세요.
libretranslate — 자체 호스팅 번역
LibreTranslate를 사용한 자체 호스팅 오픈소스 번역이에요. 로컬 또는 본인의 인프라에서 실행돼요 — API 비용 제로, 완전한 데이터 주권을 보장해요.
사용 시기: 오프라인 번역, 데이터 개인정보 보호 규정 준수(GDPR), 또는 비용 제로 운영이 필요한 프로젝트. 특히 외부 API에 의존해서는 안 되는 CI 파이프라인에 유용해요.
기능:
- ✅ 자체 호스팅 — 외부 API 호출 없음
- ✅ 무료 오픈소스 (AGPL-3.0)
- ✅ Docker 배포 가능
- ⚠️ Markdown 인식 없음 — 키-값 쌍만 지원
- ⚠️ 콘텐츠 번역 없음 — 키-값 쌍만 지원
- ⚠️ 언어 쌍에 따라 품질이 달라짐
설정:
# Run LibreTranslate locally with Docker
docker run -d -p 5000:5000 libretranslate/libretranslate
# Configure (optional — defaults to localhost:5000)
export LIBRETRANSLATE_API_URL=http://localhost:5000/translate
{
"pairs": {
"en:es": { "method": "libretranslate" }
}
}
api — 원격 번역 API
커뮤니티가 호스팅하거나 IP가 보호된 번역 엔드포인트를 위한 경량 HTTP 클라이언트예요. Champollion은 키를 내보내고 번역을 다시 받아요 — 번역 로직을 전혀 포함하지 않아요.
사용 시기: 번역 방법이 서버 측에서 호스팅되는 경우(예: 독점 코칭 데이터, 미세 조정된 모델, 배포할 수 없는 FST 파이프라인).
{
"pairs": {
"en:crk": {
"method": "api",
"endpoint": "https://api.example.com/v1/translate",
"apiKey": "your-key"
}
}
}
:::note OCAP 호환 커뮤니티 번역
api 방법은 OCAP 호환 커뮤니티 호스팅 번역으로 가는 다리예요. 원주민 및 소수 언어 커뮤니티는 자체 번역 엔드포인트를 호스팅할 수 있어요 — 코칭 데이터, 미세 조정된 모델, 언어적 IP를 커뮤니티의 통제 하에 유지하면서 — Champollion은 경량 클라이언트로서 거기에 연결돼요.
전체 커뮤니티 호스팅 안내는 저자원 언어 지원하기를, 엔드포인트 요구 사항은 API를 통해 방법 제공하기를 참고하세요. :::
쌍별 구성
진정한 강점은 언어 쌍별로 방법을 혼합하는 데 있어요:
{
"version": 3,
"pairs": {
"en:fr": { "method": "deepl" },
"en:ja": { "method": "openai", "model": "gpt-4o" },
"en:ko": { "method": "gemini" },
"en:ar": { "method": "microsoft-translator" },
"en:crk": { "methodPlugin": "crk-coached-v1" }
}
}
이렇게 하면 프랑스어는 DeepL(용어집 지원)을 통해, 일본어는 OpenAI(품질)를 통해, 한국어는 Gemini(무료 등급)를 통해, 아랍어는 Microsoft Translator(범위)를 통해, 그리고 Plains Cree는 코칭된 플러그인(특화)을 통해 번역돼요.
플러그인
플러그인은 특정 언어 쌍을 위해 미리 패키징된 번역 레시피예요. 이것은 JSON 매니페스트이며 — 코드가 아니에요 — champollion에게 어떤 방법을, 어떤 설정으로 사용할지, 그리고 어떤 품질이 벤치마크되었는지 알려줘요.
:::tip 평가 하네스에서 프로덕션까지 한 번의 명령으로
평가 하네스에서 개발하고 검증된 플러그인은 직접 설치할 수 있어요 — 거기서 검증한 방법은 단 한 번의 plugin install 명령으로 여기에 배포돼요. 전체 평가 워크플로는 MT 평가를 참고하세요.
:::
champollion plugin install ./french-formal-v1/
champollion plugin list
champollion plugin remove french-formal-v1
전체 매니페스트 형식은 플러그인 사양을 참고하세요.
제공자 전환
방법 간에 이동하시나요? 모델 형식과 환경 변수가 바뀌어요 — 여기 매핑이 있어요:
OpenRouter → 직접 제공자
{
"pairs": {
"en:fr": {
- "method": "llm",
- "model": "openai/gpt-4o"
+ "method": "openai",
+ "model": "gpt-4o"
}
}
}
- export OPENROUTER_API_KEY=sk-or-v1-...
+ export OPENAI_API_KEY=sk-proj-...
주요 차이점:
- OpenRouter는
provider/model형식을 사용해요 (예:openai/gpt-4o). 직접 제공자는 순수 모델 이름을 사용해요 (예:gpt-4o). - 각 직접 제공자에는 고유한 환경 변수가 있어요 (
OPENAI_API_KEY,ANTHROPIC_API_KEY,GEMINI_API_KEY). - 잘못된 모델 형식을 사용하면 champollion이 경고해줘요 — 모델 검증을 참고하세요.
직접 제공자 → OpenRouter
{
"pairs": {
"en:ja": {
- "method": "anthropic",
- "model": "claude-sonnet-4-6"
+ "method": "llm",
+ "model": "anthropic/claude-sonnet-4-6"
}
}
}
:::tip OpenRouter와 직접 사용 중 언제 선택할까요 환경 변수를 변경하지 않고 모델 간에 전환하고 싶거나, 단일 키로 200개 이상의 모델에 접근하고 싶을 때는 OpenRouter를 사용하세요. 더 단순한 청구, 더 낮은 지연 시간(중개자 없음), 또는 Anthropic의 프롬프트 캐싱과 같은 제공자별 기능에 접근하고 싶을 때는 직접 제공자를 사용하세요. :::
비용 비교
번역된 키 1,000개당 대략적인 비용 (키당 ~10 토큰, 배치당 80개 키 가정):
| 방법 | 1K 키당 비용 | 속도 | 품질 | 적합한 경우 |
|---|---|---|---|---|
gemini (Flash) | 무료 (등급 내) | 빠름 | 양호 | 시작하기, 개인 프로젝트 |
google-translate | ~$0.02 | 가장 빠름 | 적절 | 대량, 유럽 언어 |
deepl | ~$0.02 | 빠름 | 양호 | 유럽 언어, 용어 |
microsoft-translator | ~$0.01 | 빠름 | 적절 | Azure 환경, 광범위한 언어 범위 |
libretranslate | 무료 (자체 호스팅) | 다양 | 보통 | 격리 환경, GDPR, CI 파이프라인 |
gemini (Pro) | ~$0.07 | 중간 | 매우 좋음 | 품질에 민감한 경우, 무료 할당량 |
openai (GPT-4o-mini) | ~$0.01 | 빠름 | 양호 | 예산 LLM |
openai (GPT-4o) | ~$0.10 | 중간 | 매우 좋음 | 품질에 민감한 경우 |
anthropic (Haiku) | ~$0.01 | 빠름 | 양호 | 예산 LLM |
anthropic (Sonnet) | ~$0.10 | 중간 | 매우 좋음 | 품질에 민감한 경우 |
anthropic (Opus) | ~$0.50 | 느림 | 우수 | 최고 품질 |
llm (OpenRouter) | 모델에 따라 다름 | 다양 | 다양 | 모델 비교, 실험 |
:::note 이것은 추정치예요 실제 비용은 소스 텍스트 길이, 배치 크기, 제공자 가격 변동에 따라 달라져요. 정확한 요금은 각 제공자의 현재 가격 페이지를 확인하세요. :::
참고 자료
- 지원 언어
- 코칭 데이터
- 저자원 언어 지원하기
- 플러그인 사양
- API를 통해 방법 제공하기
- 품질 게이트
- 아키텍처
- 문제 해결 — 모델 오류, API 문제