translation-files

# MPI — Mindful Peace International

## Directory Map

| Directory | Contents |
|---|---|
| `toolkit/skills/` | Hermes Agent skills — loaded via `~/.hermes/config.yaml` `external_dirs`. [Install guide →](toolkit/skills/readme.dj) |
| `toolkit/terms-database/` | Term database (SQLite) + search CLI (`search.py`). Priority: DoT定稿 > 内部特色词 > 佛教术语 |
| `translate-files/` | Translation projects: `<topic>/<article>/` with `source.dj`, `target.dj`, `bilingual.dj` |
| `toolkit/scripts/` | Utility scripts (fish shell): `dj2docx.fish` |
| `references/` | Reference materials — Typst design notes, Google Docs review journey, formatting guides |
| `toolkit/` | Git submodule containing skills, scripts, term database, and AGENTS.md |
| `AGENTS.md` | Stub pointing to `toolkit/AGENTS.md` |

## Translation Stages

A translation project moves through the following stages in order. Each stage
has a clear output and a clear handoff to the next stage.

| Stage | What happens | Output |
|---|---|---|
| **Extract** | The source document is cleaned and converted into a plain-text working file. | `source.dj` |
| **Translate** | The Chinese source is drafted into English, matching the source line count. | `target.dj` |
| **Self-review** | The translator reviews the draft for terminology, accuracy, grammar, and flow. | `translation-findings.dj` (optional) |
| **Other-review** | A peer reviewer examines the draft and records findings for the translator. | `review-comments.dj` |
| **Polish** | Review findings are applied to the translation, and the bilingual file is regenerated. | updated `target.dj`, `bilingual.dj` |
| **Verify** | The deterministic check suite runs: line/paragraph/heading parity, emphasis preservation, CJK and Chinese-punctuation leakage, digit fidelity, bilingual freshness. Run before delivering; keep green as a regression suite. | `toolkit/scripts/check-translation.py` output, all PASS |
| **Human review** | Human translators or editors review the polished text and approve or send it back. | approved `target.dj` |
| **Typeset** | The approved bilingual content is laid out into a publishable document. | `.pdf` or `.docx` |
| **Done** | The project is complete. | — |

Reviews can send the project back to an earlier stage: self-review and
other-review may return to **Translate** if the draft needs to be redrafted,
or to **Polish** if only minor fixes are needed. Once human reviewers are
satisfied, the project moves to **Typeset** and then **Done**.

## Translating a batch of books

To translate several books at once, run one omp session per book in its own
herdr pane with the slow model (`omp --model slow --cwd <book dir>`), review
all of them in parallel, then send each pane an apply pass and gate the batch
with `check-translation.py` before packaging a zip. The full recipe, the three
canonical prompts (translate / review / apply), and the hard-won gotchas live
in `toolkit/AGENTS.md` → **Workflow C**. Proven on 9 books in a single run
(2026-08-07): every book passed all 11 checks.

## Links

Study material source repo: https://git.sr.ht/~iacore/jingxin-lessons

Translated books:

- https://en.mindfulpeace.org/bookstore
- https://www.aryaread.com/
- https://web.aryaread.com/