deusyu/translate-book

해결하는 문제

LLM을 사용하여 전체 책(PDF, DOCX, EPUB)을 번역할 경우, 컨텍스트 창 오버플로우, 출력 자르기, 일관되지 않은 용어 사용(같은 이름이 서로 다른 장에서 다르게 번역됨)이 발생합니다. 이 프로젝트는 언어적 일관성과 구조적 무결성을 유지하면서 대규모 문서를 병렬로 번역하는 자동화된 파이프라인을 제공합니다.

작동 방식

이 시스템은 Codex, Claude Code, OpenClaw와 같은 런타임용 에이전트 스킬로 작동합니다. 다음과 같은 다단계 파이프라인을 따릅니다:

1. 변환: Calibre와 Pandoc를 사용하여 입력된 책을 마크다운 청크(~6,000자씩)로 변환합니다.
2. 용어집 생성: 책에서 고유명사와 반복되는 용어를 샘플링하여, 모든 청크에서 일관된 번역을 보장하는 표준 용어집을 생성합니다.
3. 병렬 번역: 기본적으로 8개의 서브에이전트를 배포하여 청크를 동시에 번역합니다. 각 서브에이전트는 관련 용어집과 인접 청크의 짧은 개요를 받아 대명사와 엔티티를 해결합니다.
4. 검증: 매니페스트 파일을 통해 SHA-256 해시를 사용하여 모든 원본 청크에 대응되는 비어 있지 않은 번역이 존재하는지 확인합니다.
5. 재구성: 번역된 청크를 병합하고 Pandoc와 Calibre를 사용하여 최종 결과물을 HTML, DOCX, EPUB, PDF 형식으로 내보냅니다.

대상 사용자

• 형식을 유지하면서 장문 문서나 전자책을 번역해야 하는 사용자.
• AI 에이전트 프레임워크(Codex, Claude Code, OpenClaw)를 사용하여 워크플로우에 고용량 번역 기능을 추가하고자 하는 개발자.

주요 특징

• 병렬 처리: 컨텍스트 누적을 방지하고 번역 속도를 높이기 위해 격리된 서브에이전트를 사용합니다.
• 일관성 도구: 용어집 시스템과 이웃 컨텍스트 개요를 통해 용어 변동과 대명사 오류를 방지합니다.
• 재시작 가능한 워크플로우: run_state.json을 통해 상태를 추적하여 중단된 실행을 재개하거나, 용어집 변경에 영향을 받은 청크만 선택적으로 다시 번역할 수 있습니다.
• 다양한 형식 지원: PDF, EPUB, DOCX 등 다양한 입력 및 출력 형식을 처리합니다.