translate-book

Files (46)

• release.md · .claude/commands/
• FUNDING.yml · .github/
• ci.yml · .github/workflows/
• .gitignore
• AGENTS.md
• CLAUDE.md
• LICENSE
• README.md
• README.zh-CN.md
• SKILL.md
• poster-en.page · assets/poster/pages/
• poster.page · assets/poster/pages/
• style.md · assets/poster/
• translate-book-poster-en.jpg · assets/poster/
• translate-book-poster-en.pptd · assets/poster/
• translate-book-poster.jpg · assets/poster/
• translate-book-poster.pptd · assets/poster/
• calibre_html_publish.py · scripts/
• chunk_context.py · scripts/
• convert.py · scripts/
• glossary.py · scripts/
• manifest.py · scripts/
• merge_and_build.py · scripts/
• merge_meta.py · scripts/
• meta.py · scripts/
• run_state.py · scripts/
• template.html · scripts/
• template_ebook.html · scripts/
• .gitkeep · tests/.artifacts/
• README.md · tests/.artifacts/
• README.md · tests/baselines/
• SOURCE.md · tests/baselines/diligent-dick/
• diligent-dick.epub · tests/baselines/diligent-dick/
• SOURCE.md · tests/baselines/sleepy-hollow/
• sleepy-hollow.epub · tests/baselines/sleepy-hollow/
• SOURCE.md · tests/baselines/standard-alice/
• standard-alice.epub · tests/baselines/standard-alice/
• test_calibre_html_publish.py · tests/
• test_chunk_context.py · tests/
• test_convert.py · tests/
• test_glossary.py · tests/
• test_manifest.py · tests/
• test_merge_and_build.py · tests/
• test_merge_meta.py · tests/
• test_meta.py · tests/
• test_run_state.py · tests/

SKILL.md (first lines)

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

```bash
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:

   ```json
   {
     "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:

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

From deusyu/translate-book, MIT.

More from deusyu/translate-book