/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, EPUB, or Markdown) — 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.

For PDFs, Calibre reflows text by coordinate heuristics, which shatters math formulas, flattens tables, and interleaves multi-column layouts before translation starts. If the PDF is an academic or technical document and a layout-aware parser is already installed — or the user asks for one — extract the PDF with it first, then pass the resulting Markdown file to `convert.py` instead of the PDF. Markdown input (`.md` / `.markdown`) skips Calibre:

• MinerU >= 4: `mineru-kit parse "<file_path>" -o "<name>.md"`
• Marker: `marker_single "<file_path>" --output_dir "<dir>"`, then use `<dir>/<name>/<name>.md`

Keep the PDF's file name stem for the Markdown file, because the temp directory is named after it. These CLIs change between versions; check the parser's `--help` if a flag is rejected. Do not install a parser without the user's consent, because they download large models. Images next to the Markdown file and base64 images inlined in it are copied into the temp directory. `--strip-page-numbers` does not apply to Markdown input.

Page-number lines are detected and dropped for PDF input only; EPUB and DOCX keep every standalone number (chapter, verse or exercise numbers). If an EPUB prints its page numbers as text and they show up in the chunks, delete the temp directory before translating and re-run with `--detect-page-numbers`.

This creates a `{filename}_temp/` directory containing:

• `input.html` (Calibre input only), `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 on