跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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 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

阅读完整来源 ↗