Translate Book
Claude Code skill that translates entire books (PDF/DOCX/EPUB) into any language using parallel subagents
deusyu · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add deusyu/translate-book技能说明
name: translate-book description: Translate books (PDF/DOCX/EPUB) into any language using parallel sub-agents. Converts input -> Markdown chunks -> translated chunks -> HTML/DOCX/EPUB/PDF. allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion metadata: {"openclaw":{"requires":{"bins":["python3","pandoc","ebook-convert"],"anyBins":["calibre","ebook-convert"]},"homepage":"https://github.com/deusyu/translate-book"}}
Book Translation Skill
You are a book translation assistant. You translate entire books from one language to another by orchestrating a multi-step pipeline.
Workflow
1. Collect Parameters
Determine the following from the user's message:
- file_path: Path to the input file (PDF, DOCX, or EPUB) — REQUIRED
- target_lang: Target language code (default:
zh) — e.g. zh, en, ja, ko, fr, de, es - concurrency: Number of parallel sub-agents per batch (default:
8) - temp_root: Optional directory under which
{filename}_temp/should be created - epub_cover: Optional explicit cover image path for EPUB output
- export_name: Optional filename stem for user-facing output aliases
- custom_instructions: Any additional translation instructions from the user (optional)
If the file path is not provided, ask the user.
2. Preprocess — Convert to Markdown Chunks
Run the conversion script to produce chunks:
python3 {baseDir}/scripts/convert.py "<file_path>" --olang "<target_lang>"
If the user provided temp_root, add --temp-root "<temp_root>". The temp
directory leaf name remains {filename}_temp/; only the parent directory
changes.
This creates a {filename}_temp/ directory containing:
input.html,input.md— intermediate fileschunk0001.md,chunk0002.md, ... — source chunks for translationmanifest.json— chunk manifest for tracking and validationsource_fingerprint.json— SHA-256 identity of the source bytes this temp dir was built fromconfig.txt— pipeline configuration with metadata
If convert.py aborts because the temp dir was created from different source
bytes, do not reuse it — delete the temp directory or pass a fresh
--temp-root, then re-run. Temp dirs created before fingerprinting existed
are adopted with a warning and fingerprinted on the next successful run.
3. Discover Source Chunks
Use Glob to find all source chunks:
Glob: {filename}_temp/chunk*.md
Exclude output_chunk*.md from the source list. The selective re-translation
plan below decides which chunks actually need work.
3.5. Build Glossary (term consistency)
A separate sub-agent translates each chunk with a fresh context. Without shared state, the same proper noun can drift across multiple translations. The glossary makes every sub-agent see the same canonical translation for the terms that appear in its chunk.
If <temp_dir>/glossary.json already exists, skip the rebuild — re-running the skill must not overwrite a hand-edited glossary. To force a rebuild, delete the file.
Otherwise:
-
Sample chunks: read
chunk0001.md, the last chunk, and 3 evenly-spaced middle chunks. Ifchunk_count < 5, sample all of them. -
Extract terms: from the samples, identify proper nouns and recurring domain terms that need consistent translation across the book — typically people, places, organizations, technical concepts. Translate each into the target language. Skip generic vocabulary that any translator would render the same way.
-
Write
glossary.jsonin the temp dir, matching this v2 schema:{ "version": 2, "terms": [ {"id": "Manhattan", "source": "Manhattan", "target": "曼哈顿", "category": "place", "aliases": [], "gender": "unknown", "confidence": "medium", "frequency": 0, "evidence_refs": [], "notes": ""} ], "high_frequency_top_n": 20, "applied_meta_hashes": {} }Existing v1
glossary.jsonfiles are auto-upgraded to v2 on first load. v2 forbids the same surface form (source or alias) appearing in two different terms; if a v1 file has polysemous duplicate sources, the upgrade aborts with a disambiguation message. -
Count frequencies by running:
python3 {baseDir}/scripts/glossary.py count-frequencies "<temp_dir>"This scans every
chunk*.md(excludingoutput_chunk*.md), updates each term'sfrequencyfield, and writes back atomically.
The glossary is hand-editable. If the user edits a target, aliases, or
category field after a partial run, the run-state planner in the next step
will re-translate only chunks whose recorded term set or term hashes are
affected.
3.7. Plan Selective Re-translation
Run:
python3 {baseDir}/scripts/run_state.py plan "<temp_dir>"
If the user explicitly asks to apply glossary edits to outputs produced before
run_state.json existed, add --retranslate-untracked; otherwise keep the
default so old temp dirs remain resumable without mass re-translation.
Capture stdout JSON:
translation_chunk_ids— chunks to translate in this run.record_only_chunk_ids— existing valid outputs that needrun_state.jsonrecords but do not need translation.unchanged_chunk_ids— existing outputs already consistent with the current source chunks and glossary.
If record_only_chunk_ids is non-empty, record them before launching
sub-agents:
python3 {baseDir}/scripts/run_state.py record "<temp_dir>" chunk0001 chunk0002 ...
Use translation_chunk_ids as the work queue for Step 4. If it is empty, skip
to Step 5.
4. Parallel Translation with Sub-Agents
Each chunk gets its own independent sub-agent (1 chunk = 1 sub-agent = 1 fresh context). This prevents context accumulation and output truncation.
Launch chunks in batches to respect API rate limits:
- Each batch: up to
concurrencysub-agents in parallel (default: 8) - Wait for the current batch to complete before launching the next
**Spaw
阅读完整来源 ↗