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.

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

Run:

```bash
python3 {baseDir}/scripts/run_state.py plan "<temp_dir>"
```

From deusyu/translate-book, MIT.

More from deusyu/translate-book