/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 files
• `chunk0001.md`, `chunk0002.md`, ... — source chunks for translation
• `manifest.json` — chunk manifest for tracking and validation
• `source_fingerprint.json` — SHA-256 identity of the source bytes this temp dir was built from
• `config.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:

1. **Sample chunks**: read `chunk0001.md`, the last chunk, and 3 evenly-spaced middle chunks. If `chunk_count < 5`, sample all of them. 2. **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. 3. **Write `glossary.json`** in 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.json` files 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.

4. **Count frequencies** by running:

   python3 {baseDir}/scripts/glossary.py count-frequencies "<temp_dir>"

This scans every `chunk*.md` (excluding `output_chunk*.md`), updates each term's `frequency` field, 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 need `run_state.json`

records 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 `concurrency` sub-agents in parallel (default: 8)
• Wait for the current batch to complete before launching the next

**Spaw