translate-book

translate-book 스킬 개요

translate-book이 하는 일

translate-book 스킬은 PDF, DOCX, EPUB 파일을 위한 도서 번역 파이프라인입니다. 원본 책을 Markdown 청크로 나눈 뒤, 각 청크를 병렬 서브 에이전트로 번역하고, 결과를 HTML, DOCX, EPUB, PDF로 다시 재구성합니다. 긴 형식의 콘텐츠를 번역할 때 translate-book가 필요하다면, 한 번의 프롬프트로 한 권 전체를 처리하기엔 너무 불안정하거나 지속성이 짧을 때 특히 유용합니다.

누가 설치하면 좋은가

책, 매뉴얼, 또는 책 분량의 문서를 자주 번역하고, 반복 가능한 결과와 청크 단위 재개, 형식 재생성을 중요하게 생각한다면 translate-book를 설치하는 것이 좋습니다. 처음부터 일회성 번역 프롬프트를 직접 짜는 대신, 안내된 워크플로를 원하는 사용자에게 잘 맞습니다. 짧은 발췌문이나 빠른 요약만 필요하다면 효용은 떨어집니다.

무엇이 다른가

translate-book 스킬의 핵심 차별점은 파이프라인 설계에 있습니다. 변환, 청크 분할, 병렬 번역, 해시 검증, 재구성이 모두 명시적인 단계로 분리되어 있습니다. 이런 구조는 문맥 손실을 줄이고, 최종 조립 전에 누락되었거나 오래된 청크를 잡아내는 데 도움이 됩니다. 또한 저장소가 도구 체인과 출력 산출물에 대해 강한 의견을 갖고 있어, 단순한 “이 파일을 번역해 주세요”형 프롬프트보다 설치 판단이 훨씬 명확합니다.

translate-book 스킬 사용법

설치하고 전제 조건 확인하기

프로젝트가 안내하는 설치 흐름을 따라 설치한 뒤, 파이프라인이 기대하는 외부 도구가 있는지 확인하세요: python3, pandoc, 그리고 Calibre의 ebook-convert 또는 calibre입니다. ebook-convert가 없으면 translate-book install 단계는 성공하더라도 변환 시점에서 워크플로가 실패할 수 있으므로, 먼저 실행 환경을 검증하는 것이 좋습니다.

완전한 입력 프롬프트로 시작하기

이 스킬은 파일 경로, 대상 언어, 스타일 제약을 한 번에 주었을 때 가장 잘 작동합니다. 예를 들면 이런 식입니다: Translate /path/to/book.epub into Japanese, keep technical terms consistent, preserve chapter structure, and use a formal tone. 이렇게 하면 translate-book usage가 충분한 맥락을 바탕으로 매개변수를 고르고, 불필요한 왕복을 줄일 수 있습니다. 파일 경로를 생략하면 스킬이 멈추고 해당 정보를 요청해야 합니다.

먼저 읽어야 할 파일을 정확히 보기

설치 관점에서 확신을 얻고 싶다면 먼저 SKILL.md를 읽고, 구현과 테스트 메모가 필요하다면 README.md, AGENTS.md, CLAUDE.md를 이어서 확인하세요. 이 저장소에서는 README를 훑는 것보다 스크립트를 보는 편이 훨씬 중요합니다. scripts/convert.py, scripts/manifest.py, scripts/glossary.py, scripts/merge_and_build.py가 청크가 어떻게 생성되고, 추적되고, 일관성이 유지되고, 다시 조립되는지 설명합니다. translate-book가 자신의 워크플로에 맞는지 가장 빨리 판단하는 방법도 바로 이것입니다.

청크를 인식하는 워크플로 사용하기

이것을 하나의 번역 호출로 생각하면 안 됩니다. 의도된 흐름은 입력 파일 → Markdown 청크 → 번역된 청크 출력 → 병합된 책입니다. 프롬프트를 줄 때는 청크 품질에 영향을 주는 요소를 명시하세요. 각주, 표, 코드 블록이 반드시 살아 있어야 하는지, 이름을 번역하지 않아야 하는지, 책 전체에서 용어집 일관성이 필요한지 등을 밝혀두는 것이 좋습니다. 이런 세부 정보는 서브 에이전트가 나중에 충돌하는 지역적 선택을 덜 하도록 도와줍니다.

translate-book 스킬 FAQ

translate-book은 초보자에게도 쉬운가요?

파일 경로와 대상 언어를 제공할 수 있다면 그렇습니다. 이 스킬은 다단계 파이프라인을 감춰 주지만, 서식 보존과 용어 일관성 같은 책 단위 제약은 여전히 이해하고 있어야 합니다. 초보자라면 큰 스캔 PDF에 바로 도전하기보다, 짧은 EPUB이나 DOCX부터 시작하는 편이 보통 더 좋은 결과를 얻습니다.

언제 translate-book을 쓰지 말아야 하나요?

짧은 문장, 가벼운 대화형 번역, 또는 대략적인 요지만 필요할 때는 사용하지 않는 것이 좋습니다. OCR 품질이 낮은 스캔 PDF처럼 심하게 훼손된 입력에도 덜 적합합니다. 원본 변환 품질이 낮으면 이후 번역 품질도 그만큼 제한됩니다. 입력 파일을 깔끔하게 변환할 수 없다면, 어떤 프롬프트로도 구조를 완전히 복구할 수는 없습니다.

일반 번역 프롬프트와 무엇이 다른가요?

일반 프롬프트는 보통 한 번의 컨텍스트 창 안에서 번역되기 때문에, 잘림, 내용 흔들림, 용어 불일치에 취약합니다. translate-book는 청킹, 검증, 재구성 단계 위에 만들어져 있어, 연속성이 중요한 긴 문서에 더 적합합니다. 그 대신 설정이 더 필요하고 의존성 확인도 더 많이 해야 합니다.

translate-book은 어떤 언어 조합이든 가능한가요?

이 저장소는 여러 대상 언어를 염두에 두고 설계되었지만, 품질은 여전히 원문의 복잡도와 용어 밀도에 좌우됩니다. 가장 좋은 결과는 대상 언어 코드를 명시하고, 도메인 용어에 대한 용어집 지침을 함께 줄 때 나옵니다. 번역 비중이 큰 프로젝트에서는 이런 일관성 지침이 언어 선택만큼이나 중요합니다.

translate-book 스킬 개선 방법

원본 제약 조건을 더 분명하게 주기

가장 큰 품질 향상은 translate-book가 무엇을 바꾸면 안 되는지 명확히 알려줄 때 나옵니다. 유지해야 할 장 제목, 영어로 남길 용어, 선호하는 음역, 표나 코드 블록의 서식 규칙, 그리고 학술적 톤인지 일반 독자용 톤인지 같은 독자 수준을 제공하세요. 예를 들면: Keep API names unchanged, translate prose formally, and preserve Markdown headings exactly.

용어집 흔들림을 초기에 줄이기

파이프라인이 병렬 서브 에이전트를 사용하므로, 핵심 용어를 미리 정의하지 않으면 용어가 쉽게 흔들릴 수 있습니다. 큰 책을 돌리기 전에 이름, 제품 용어, 반복되는 기술 표현으로 된 작은 용어집을 준비하세요. 특히 translate-book for Translation 프로젝트에서는 하나의 일관성 없는 용어가 여러 청크로 퍼질 수 있으므로 더 중요합니다.

변환과 청크 분할 실패를 점검하기

자주 발생하는 실패는 OCR 오류, 원본 서식 불량, 그리고 표나 목록을 어색하게 끊어버리는 청크 경계입니다. 첫 결과가 들쭉날쭉해 보인다면, 번역 품질을 탓하기 전에 중간 청크 파일과 매니페스트를 먼저 확인하세요. 가장 유용한 translate-book guide 습관은 원본 파이프라인을 먼저 고치고, 깨끗한 청크로 번역을 다시 실행하는 것입니다.

첫 결과를 바탕으로 반복 개선하기

첫 번째 패스가 끝나면 최종 병합본만 보지 말고, 대표적인 청크 몇 개를 골라 검토하세요. 장 서두, 용어집 항목, 제목, 그리고 원본에 복잡한 서식이 있었던 부분을 확인하면 좋습니다. 필요하다면 책 전체를 손으로 편집하기보다 더 엄격한 지시로 다시 실행하는 편이 낫습니다. 다음 translate-book skill 실행을 개선하는 가장 빠른 방법이기 때문입니다.