# deusyu/translate-book architecture

> Architecture diagram of the GitHub repository deusyu/translate-book, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deusyu/translate-book
- Repository: https://github.com/deusyu/translate-book

## Overview

Rainman Translate Book is an agent skill and Python-backed pipeline for translating whole books in independently translated chunks, then validating and exporting the result. The documented workflow runs from a book or Markdown input through conversion, chunking, parallel agent translation, integrity checks, and multi-format publishing. Glossary observations and run state support terminology consistency and selective resumption. The orchestration links are based on the README; sampled excerpts clarify helper behavior, but do not expose the complete skill instructions or all script call sites.

Main entry points: [`SKILL.md`](https://github.com/deusyu/translate-book/blob/main/SKILL.md) (Agent skill), [`scripts/convert.py`](https://github.com/deusyu/translate-book/blob/main/scripts/convert.py) (Convert and chunk), [`scripts/merge_and_build.py`](https://github.com/deusyu/translate-book/blob/main/scripts/merge_and_build.py) (Merge and build), [`scripts/merge_meta.py`](https://github.com/deusyu/translate-book/blob/main/scripts/merge_meta.py) (Merge observations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversion["Input conversion"]
  node_convert["Convert and chunk<br/>[convert.py]"]
  node_chunks["Source chunks"]
end

subgraph group_translation["Translation workflow"]
  node_skill["Agent skill<br/>[SKILL.md]"]
  node_agents["Translation subagents"]
  node_context["Neighbor excerpts<br/>[chunk_context.py]"]
  node_outputs["Translated chunks"]
end

subgraph group_consistency["Consistency and integrity"]
  node_manifest["Chunk manifest<br/>[manifest.py]"]
  node_glossary[("Term glossary<br/>[glossary.py]")]
  node_runstate[("Resume state<br/>[run_state.py]")]
  node_meta["Chunk observations<br/>[meta.py]"]
  node_merge_meta["Merge observations<br/>[merge_meta.py]"]
  node_validate["Manifest validation<br/>[manifest.py]"]
end

subgraph group_publishing["Merge and publishing"]
  node_build["Merge and build<br/>[merge_and_build.py]"]
  node_publisher["Calibre publisher"]
end

node_reader(("Book requester"))
node_source["Book or Markdown"]
node_calibre["Calibre"]
node_pandoc["Pandoc"]
node_final["HTML DOCX EPUB PDF"]

node_reader -->|"requests translation"| node_skill
node_reader -->|"provides input"| node_source
node_skill -->|"runs conversion"| node_convert
node_convert -->|"reads input"| node_source
node_convert -.->|"converts formats"| node_calibre
node_convert -->|"writes chunks"| node_chunks
node_convert -->|"records hashes"| node_manifest
node_skill -->|"dispatches chunks"| node_agents
node_agents -->|"reads chunks"| node_chunks
node_skill -->|"gets excerpts"| node_context
node_context -->|"reads neighbors"| node_chunks
node_skill -->|"provides terms"| node_glossary
node_agents -->|"writes translations"| node_outputs
node_agents -->|"writes observations"| node_meta
node_skill -->|"checks progress"| node_runstate
node_skill -->|"merges observations"| node_merge_meta
node_merge_meta -->|"reads observations"| node_meta
node_merge_meta -->|"updates terms"| node_glossary
node_skill -->|"requests validation"| node_validate
node_validate -->|"checks hashes"| node_manifest
node_validate -->|"checks matches"| node_outputs
node_skill -->|"runs build"| node_build
node_build -->|"merges chunks"| node_outputs
node_build -->|"converts documents"| node_pandoc
node_build -->|"exports formats"| node_publisher
node_publisher -->|"converts HTML"| node_calibre
node_build -->|"writes HTML"| node_final
node_publisher -->|"writes formats"| node_final

click node_skill "https://github.com/deusyu/translate-book/blob/main/SKILL.md"
click node_convert "https://github.com/deusyu/translate-book/blob/main/scripts/convert.py"
click node_manifest "https://github.com/deusyu/translate-book/blob/main/scripts/manifest.py"
click node_context "https://github.com/deusyu/translate-book/blob/main/scripts/chunk_context.py"
click node_glossary "https://github.com/deusyu/translate-book/blob/main/scripts/glossary.py"
click node_runstate "https://github.com/deusyu/translate-book/blob/main/scripts/run_state.py"
click node_meta "https://github.com/deusyu/translate-book/blob/main/scripts/meta.py"
click node_merge_meta "https://github.com/deusyu/translate-book/blob/main/scripts/merge_meta.py"
click node_validate "https://github.com/deusyu/translate-book/blob/main/scripts/manifest.py"
click node_build "https://github.com/deusyu/translate-book/blob/main/scripts/merge_and_build.py"
click node_publisher "https://github.com/deusyu/translate-book/blob/main/scripts/calibre_html_publish.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_convert,node_chunks toneBlue
class node_skill,node_agents,node_context,node_outputs toneAmber
class node_manifest,node_glossary,node_runstate,node_meta,node_merge_meta,node_validate,node_reader toneMint
class node_build,node_publisher toneRose
class node_source,node_calibre,node_pandoc,node_final toneIndigo
```

## Components

### Input conversion

- [Convert and chunk](https://github.com/deusyu/translate-book/blob/main/scripts/convert.py): `scripts/convert.py`
- **Source chunks**

### Translation workflow

- [Agent skill](https://github.com/deusyu/translate-book/blob/main/SKILL.md): `SKILL.md`
- **Translation subagents**
- [Neighbor excerpts](https://github.com/deusyu/translate-book/blob/main/scripts/chunk_context.py): `scripts/chunk_context.py`
- **Translated chunks**

### Consistency and integrity

- [Chunk manifest](https://github.com/deusyu/translate-book/blob/main/scripts/manifest.py): `scripts/manifest.py`
- [Term glossary](https://github.com/deusyu/translate-book/blob/main/scripts/glossary.py): `scripts/glossary.py`
- [Resume state](https://github.com/deusyu/translate-book/blob/main/scripts/run_state.py): `scripts/run_state.py`
- [Chunk observations](https://github.com/deusyu/translate-book/blob/main/scripts/meta.py): `scripts/meta.py`
- [Merge observations](https://github.com/deusyu/translate-book/blob/main/scripts/merge_meta.py): `scripts/merge_meta.py`
- [Manifest validation](https://github.com/deusyu/translate-book/blob/main/scripts/manifest.py): `scripts/manifest.py`

### Merge and publishing

- [Merge and build](https://github.com/deusyu/translate-book/blob/main/scripts/merge_and_build.py): `scripts/merge_and_build.py`
- [Calibre publisher](https://github.com/deusyu/translate-book/blob/main/scripts/calibre_html_publish.py): `scripts/calibre_html_publish.py`

### Other components

- **Book requester**
- **Book or Markdown**
- **Calibre**
- **Pandoc**
- **HTML DOCX EPUB PDF**

## Connections

- Book requester → Agent skill: requests translation
- Book requester → Book or Markdown: provides input
- Agent skill → Convert and chunk: runs conversion
- Convert and chunk → Book or Markdown: reads input
- Convert and chunk → Calibre: converts formats
- Convert and chunk → Source chunks: writes chunks
- Convert and chunk → Chunk manifest: records hashes
- Agent skill → Translation subagents: dispatches chunks
- Translation subagents → Source chunks: reads chunks
- Agent skill → Neighbor excerpts: gets excerpts
- Neighbor excerpts → Source chunks: reads neighbors
- Agent skill → Term glossary: provides terms
- Translation subagents → Translated chunks: writes translations
- Translation subagents → Chunk observations: writes observations
- Agent skill → Resume state: checks progress
- Agent skill → Merge observations: merges observations
- Merge observations → Chunk observations: reads observations
- Merge observations → Term glossary: updates terms
- Agent skill → Manifest validation: requests validation
- Manifest validation → Chunk manifest: checks hashes
- Manifest validation → Translated chunks: checks matches
- Agent skill → Merge and build: runs build
- Merge and build → Translated chunks: merges chunks
- Merge and build → Pandoc: converts documents
- Merge and build → Calibre publisher: exports formats
- Calibre publisher → Calibre: converts HTML
- Merge and build → HTML DOCX EPUB PDF: writes HTML
- Calibre publisher → HTML DOCX EPUB PDF: writes formats