Lingo.dev CLI는 하나의 i18n.json 설정 파일을 읽고, 소스 파일에서 번역 가능한 문자열을 추출한 다음, 이를 로컬라이제이션 엔진 또는 LLM 제공업체로 보내 앱과 콘텐츠를 번역합니다. 번역 결과는 다시 디스크에 기록되며, 변경 사항도 함께 추적하므로 다음 실행에서는 델타만 처리하면 됩니다.
5단계 파이프라인#
npx lingo.dev@latest run을 실행하면 CLI가 다음 다섯 단계를 순서대로 수행합니다:
콘텐츠 탐색
CLI는 i18n.json에 있는 bucket configurations를 기준으로 프로젝트의 소스 파일과 대상 파일을 스캔합니다. 각 버킷은 파일 형식과 include/exclude 패턴 세트를 정의하며, 이를 통해 CLI가 번역 가능한 콘텐츠의 위치를 파악합니다.
{
"locale": {
"source": "en",
"targets": ["es", "fr", "de"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
}
}[locale] 플레이스홀더는 런타임에 설정된 소스 및 대상 로캘 코드로 해석됩니다.
데이터 정리
모든 콘텐츠를 번역할 필요는 없습니다. CLI는 언어가 바뀌어도 그대로 유지되어야 하는 값, 즉 숫자, 불리언, ISO 날짜, UUID, URL, 빈 문자열을 걸러냅니다. 이렇게 하면 번역 백엔드로 전송되는 페이로드가 줄어들어 토큰 사용량과 처리 시간도 함께 줄어듭니다.
델타 계산
CLI는 모든 소스 문자열에 대해 SHA-256 핑거프린트를 계산하고, 이를 i18n.lock에 저장된 이전 상태와 비교합니다. 새로 추가되었거나 수정된 콘텐츠만 번역 파이프라인에 들어가며, 변경되지 않은 문자열은 완전히 건너뜁니다.
이 점진적 방식 덕분에 키가 10,000개인 프로젝트에서 12개만 바뀌었다면, 전체가 아니라 그 12개 키만 번역합니다.
로컬라이제이션
계산된 델타는 설정된 번역 백엔드로 전송됩니다. CLI는 두 가지 모드를 지원합니다:
| 모드 | 작동 방식 |
|---|---|
| Lingo.dev 엔진 | 요청을 로컬라이제이션 엔진을 통해 전달하면서 브랜드 보이스, glossary, instructions, model configuration을 자동으로 적용합니다. |
| Raw LLM provider | 번역 요청을 커스텀 프롬프트와 함께 OpenAI, Anthropic, Google, Mistral, OpenRouter 또는 Ollama로 직접 전송합니다. |
CLI는 실패한 요청을 지수 백오프로 재시도하고, 중간 진행 상황을 저장하며, 여러 대상 언어를 동시에 처리합니다.
콘텐츠 반영
번역된 문자열은 소스 콘텐츠가 있던 정확한 위치에 다시 디스크로 기록됩니다. CLI는 파일 구조와 서식을 유지해 검토하기 쉬운 최소한의 diff를 만들어냅니다. 프로젝트에 Prettier가 설정되어 있다면 출력도 해당 서식 규칙을 따릅니다.
출력 파일#
일반적인 실행 결과로는 두 가지 유형의 변경 사항이 생깁니다:
- 로캘 파일 - 새 번역과 수정된 번역이 반영된 대상 언어 파일
i18n.lock- 상태 추적을 위한 콘텐츠 핑거프린트가 업데이트됨
두 항목 모두 버전 관리에 커밋해야 하며, 수동으로 하거나 CI/CD integration을 통해 자동으로 처리할 수 있습니다.
