문제 해결

champollion의 일반적인 문제와 해결 방법입니다.

API & 인증

"OPENROUTER_API_KEY not found"

Champollion은 LLM 번역을 위해 API 키가 필요해요. 환경 변수로 설정하세요:

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

또는 .env 파일에 설정하세요 (프로젝트가 .env 파일을 로드하는 경우):

OPENROUTER_API_KEY=sk-or-v1-...

팁

Google Translate API 키만 있는 경우, champollion이 이를 자동으로 감지하여 Google Translate를 기본 방식으로 사용해요. 설정을 변경할 필요가 없어요.

OpenRouter에서 "401 Unauthorized" 발생

API 키가 유효하지 않거나 만료되었어요. openrouter.ai/keys에서 확인하세요.

"429 Too Many Requests" / 속도 제한

Champollion은 지수 백오프를 통해 속도 제한을 내부적으로 처리해요. 속도 제한에 계속 걸린다면:

설정에서 배치 크기를 줄이세요:
```
{ "batchSize": 15 }
```
더 높은 속도 제한을 가진 모델을 사용하세요 (예: google/gemini-3.5-flash는 넉넉한 제한을 제공해요)
대용량 페어에는 더 저렴하거나 빠른 방식을 사용하세요 — Google Translate에는 속도 제한이 없어요:
```
{ "pairs": { "en:it": { "method": "google-translate" } } }
```

모델을 찾을 수 없음 / 404 오류

직접 LLM 제공업체(openai, anthropic, gemini)는 첫 사용 시 모델 문자열을 검증해요. 다음과 같은 경고가 표시되면:

"looks like an OpenRouter path" — 직접 제공업체에서 OpenRouter 형식의 모델(google/gemini-3.5-flash)을 사용하고 있어요. 직접 제공업체는 단순 모델 이름을 사용해요:

- { "method": "gemini", "model": "google/gemini-3.5-flash" }
+ { "method": "gemini", "model": "gemini-2.5-flash" }

또는 OpenRouter를 사용하려면 llm 방식으로 전환하세요:

{ "method": "llm", "model": "google/gemini-3.5-flash" }

"is an Anthropic/OpenAI/Gemini model" — 잘못된 제공업체로 모델을 보내고 있어요:

- { "method": "gemini", "model": "claude-sonnet-4-6" }
+ { "method": "anthropic", "model": "claude-sonnet-4-6" }

"not found in available models" — 모델이 더 이상 사용되지 않거나 철자가 틀렸을 수 있어요. Champollion은 제공업체의 실시간 모델 목록을 가져와 대안을 제안해요. 현재 모델 이름은 제공업체의 문서를 확인하세요.

:::tip 모델 지원 중단이 발생해요 제공업체는 정기적으로 모델 이름을 폐기해요. 제공업체 업데이트 후 갑자기 번역이 실패하면 [WARN] 출력을 확인하세요 — 현재 사용 가능한 대안을 보여줄 거예요. :::

번역 품질

번역이 원본 언어를 그대로 반복함

품질 게이트가 이를 잡아내요. 번역이 영어 원본과 동일하면 거부되고 재시도돼요. 이 문제가 계속되면:

모델을 확인하세요 — 일부 모델은 특정 언어 페어에서 성능이 좋지 않아요
레지스터 지시문을 추가하세요 — 모델에게 어떤 언어를 생성해야 하는지 알려주세요:
```
{
  "languages": {
    "ja": { "name": "Japanese", "register": "Polite/formal Japanese" }
  }
}
```
다른 모델을 사용해 보세요 — gpt-4o-mini에서 gpt-4o 또는 google/gemini-2.5-pro로 전환하세요

잘못된 문자 체계 출력 (예: 일본어에 라틴 문자 사용)

품질 게이트의 문자 체계 준수 검사가 대부분의 경우를 잡아내요. 이 문제가 계속되면:

로케일 코드가 올바른지 확인하세요 (jp가 아니라 ja)
register 필드에 명시적인 문자 체계 지시문을 추가하세요:
```
{ "register": "Japanese using hiragana, katakana, and kanji" }
```

출력의 환각 패턴

반복되는 트라이그램 패턴(예: "hello hello hello")은 환각 루프 감지기가 잡아내요. 출력이 깨졌지만 감지기를 통과하는 경우:

배치 크기를 줄이세요 — 더 작은 배치는 더 집중된 출력을 생성해요
더 강력한 모델을 사용하세요 — 더 큰 모델은 비라틴 문자 체계에서 환각이 덜 발생해요
코칭 데이터를 추가하세요 — 사전 용어가 번역을 고정시켜줘요

파일 & 형식 문제

"No locale files found"

Champollion은 로케일 파일을 자동으로 감지해요. 찾을 수 없는 경우:

localesDir를 확인하세요 — 로케일 파일이 있는 디렉터리를 가리켜야 해요:
```
{ "localesDir": "./locales" }
```
파일 이름을 확인하세요 — 파일은 로케일 코드로 이름이 지정되어야 해요: en.json, fr.json 등
형식을 확인하세요 — 지원되는 형식: JSON, 중첩 JSON, YAML, TOML

잠금 파일 충돌

.champollion.lock가 잘못된 상태가 되면:

# Reset the lock file (next sync will retranslate everything)
rm .champollion.lock
npx champollion sync

경고

잠금 파일을 삭제하면 다음 동기화 시 변경된 키뿐만 아니라 모든 키를 재번역해요. 대규모 프로젝트의 경우 API 비용에 영향을 줘요.

특정 키 재번역하기

개별 번역이 잘못되어 잠금 파일을 삭제하지 않고 강제로 재번역하려는 경우:

# Re-translate a single key
npx champollion sync --force-keys "hero.title"

# Re-translate multiple keys
npx champollion sync --force-keys "nav.home,nav.about,footer.copyright"

--force-keys 플래그는 해당 특정 키에 대한 잠금 파일 해시 검사를 무시하여 다른 키에 영향을 주지 않고 재번역을 강제해요.

콘텐츠 번역이 코드 블록을 손상시킴

이런 일은 발생하지 않아야 해요 — 코드 블록은 번역 전에 보호돼요. 만약 발생한다면:

코드 블록이 표준 펜싱(삼중 백틱)을 사용하는지 확인하세요
원본 Markdown에 닫히지 않은 코드 블록이 있는지 확인하세요
이슈를 제출하세요 — 이것은 센티넬 보호 시스템의 버그예요

CLI 문제

`--watch`가 변경 사항을 감지하지 못함

파일 감시는 Node.js 네이티브 fs.watch을 사용해요. 알려진 문제:

네트워크 드라이브 — fs.watch는 NFS/SMB 마운트에서 안정적으로 작동하지 않아요
Docker 볼륨 — 폴링 모드를 사용하거나 컨테이너 내부에서 champollion을 실행하세요
대규모 디렉터리 — 감시기는 localesDir을 재귀적으로 모니터링해요; 매우 깊은 트리는 OS 제한을 초과할 수 있어요

`npx`가 이전 버전을 실행함

# Clear the npx cache
npx --yes champollion@latest sync

또는 전역으로 설치하세요:

npm install -g champollion
champollion sync

성능

여러 언어에 대해 동기화가 느림

Champollion은 기본적으로 모든 로케일을 병렬로 번역해요. 그래도 동기화가 느린 경우:

대용량 페어에는 Google Translate를 사용하세요 — LLM 번역보다 10~50배 빨라요
배치 크기를 늘리세요 (기본값은 80):
```
{ "batchSize": 120 }
```
동시성을 조정하세요 — JSON 로케일 병렬성은 기본값이 200이고 콘텐츠는 48이에요. API 제공업체가 더 높은 속도 제한을 지원하는 경우:
```
npx champollion sync --json-concurrency 80 --content-concurrency 20
```
빠른 모델을 사용하세요 — gpt-4o-mini는 gpt-4o보다 훨씬 빨라요

높은 API 비용

배치 크기를 확인하세요 — 더 큰 배치 = 더 적은 API 호출 = 더 낮은 비용
Translation Memory를 사용하세요 — TM은 기본적으로 켜져 있어요. champollion tm stats를 실행하여 작동하는지 확인하세요. 여러 번 동기화한 후에도 0개의 항목이 표시되면 .champollion/ 디렉터리 권한에 문제가 있을 수 있어요
프롬프트 캐싱을 사용하세요 — Champollion은 Anthropic 및 Google 모델에서 캐시 적중을 위해 시스템/사용자 메시지를 분리해요
Tier 2 언어에는 Google Translate를 사용하세요 — 30개 언어 번역하기 쿡북을 참조하세요

제공업체 전환 후 오래된 번역

한 번역 방식에서 다른 방식으로 전환하는 경우(예: llm에서 deepl로), TM 캐시는 원본 텍스트가 변경되지 않은 키에 대해 이전 방식의 오래된 번역을 계속 제공할 수 있어요. 캐시 키에는 방식 이름이 포함되어 있어 대부분의 경우 자동으로 처리돼요. 하지만 같은 방식 내에서 model을 변경한 경우:

# Force fresh translations for all keys
champollion sync --no-tm

# Or clear the cache entirely and re-sync
champollion tm clear --yes
champollion sync

캐시 키 설계에 대한 자세한 내용은 Translation Memory를 참조하세요.

여전히 막혔나요?

GitHub Issues — 기존 이슈를 검색하거나 새 이슈를 제출하세요
아키텍처 문서 — 시스템 설계를 이해하세요
품질 게이트 — 검증이 내부적으로 어떻게 작동하는지 알아보세요

API & 인증​

"OPENROUTER_API_KEY not found"​

OpenRouter에서 "401 Unauthorized" 발생​

"429 Too Many Requests" / 속도 제한​

모델을 찾을 수 없음 / 404 오류​

번역 품질​

번역이 원본 언어를 그대로 반복함​

잘못된 문자 체계 출력 (예: 일본어에 라틴 문자 사용)​

출력의 환각 패턴​

파일 & 형식 문제​

"No locale files found"​

잠금 파일 충돌​

특정 키 재번역하기​

콘텐츠 번역이 코드 블록을 손상시킴​

CLI 문제​

--watch가 변경 사항을 감지하지 못함​

npx가 이전 버전을 실행함​

성능​

여러 언어에 대해 동기화가 느림​

높은 API 비용​

제공업체 전환 후 오래된 번역​

여전히 막혔나요?​