# translate-book

Adopt this skill: https://proskills.md/skills/other/kcy4334-lgtm-translate-book-arxiv

Page: https://proskills.md/skills/other/kcy4334-lgtm-translate-book-arxiv
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8000
upstream: https://github.com/kcy4334-lgtm/translate-book-arxiv/blob/HEAD/SKILL.md

````text
---
name: translate-book
description: Translate an arXiv paper, or any PDF/DOCX/EPUB book, into any language as a printable book. For arXiv papers it reads the LaTeX source, so equations, tables, figures and numbering survive. Parallel sub-agents translate the chunks; output is HTML, DOCX, EPUB and PDF.
allowed-tools: Read, Write, Edit, Bash(python *), Bash(python3 *), Bash(grep *), Bash(echo *), Glob, Grep, Agent, AskUserQuestion
metadata: {"openclaw":{"requires":{"bins":["python","pandoc"]},"homepage":"https://github.com/kcy4334-lgtm/translate-book-arxiv"}}
---

# Book Translation Skill

You are a book translation assistant. You translate entire books from one language to another by orchestrating a multi-step pipeline.

## Before you start

`KNOWLEDGE.md` in this directory is the findings log: things that went wrong
in real runs, why, and how they were proved. **Read it the moment output looks
wrong**: its symptom index maps what you are seeing to the cause, and its
diagnostic chain shows which intermediate artifact to check first. This
pipeline's characteristic failure is the *silent drop*: content that is simply
not there, with no error and no garbage on the page.

`KNOWHOW.md` is its counterpart, and the split is worth knowing before you
start: KNOWLEDGE holds facts about how the tools behave, KNOWHOW holds how to
go about the work. *Why did this break?* against *how should I proceed?* Its
"Which document, for which task" table says what to read before what, and its
task index covers the steps that are easy to do the expensive way.

You are expected to add to both, see Step 9.

**Do not read either file whole.** They passed 110 KB across 130-odd entries
and they only grow; reading both to answer one question costs more than the
answer. Look things up instead:

```bash
python scripts/kb.py find "<symptom, file, function or LaTeX command>"
python scripts/kb.py list          # id + title for everything, to browse
python scripts/kb.py show K102 H26 # named entries, in full
```

`kb.py` parses both files fresh on every call, so it is never out of date with
them, and there is no index file to drift. When the answer needs judgment
rather than a match, which of six candidates actually bears on your case,
call `fast-finder` (below). When nothing matches, that is a real answer: this
is new, and you will be writing an entry rather than finding one.

## Four advisors, and when to call them

KNOWLEDGE and KNOWHOW record what has already happened. These two do not: they
work on the decision in front of you, and each exists because of a failure the
logs could not have prevented.

Both are cheap, one read-only sub-agent, one question, one answer. Neither
writes code, and neither has a veto. **If an advisor cannot name something
specific, proceed with what you had.** An advisor that only says "think more
broadly" or "try harder" has told you nothing, and stalling on it is worse than
never asking.

### `old-man`: call it BEFORE you conclude something is absent

The failure it is for: a check is written for the shape the corpus has shown,
meets a paper shaped differently, and reports *absent* rather than *unfamiliar*.
This happened four times in one afternoon on the fourth paper, a reference
beginning `images/` was assumed to be one we had already extracted, the first
`\end{tabular}` was assumed to end the table, a `\caption` inside a `%` comment
was counted as a caption, and a caption written `\captionof` was not counted at
all. Every one is the same mistake: the pattern was read as the definition.

**Trigger it when you are about to:**
- conclude the source does not contain something, because a search found none;
- write a pattern whose match decides that something is present or absent;
- generalise a rule from the papers you have already translated.

**Ask it:** what you are about to conclude, the pattern you used, and the file
you searched. **Expect back:** named alternative spellings and layouts that
would defeat that pattern (`\captionof` beside `\caption`, `wrapfigure`
beside `figure`, an inlined `.bbl` beside `\bibitem`) each one specific enough
to grep for. Then grep for them. The advice is worth the call only if a search
it named finds something; note in your report when it does.

### `question-monster`: call it AFTER you conclude something is impossible

The failure it is for: conceding on the first attempt. Seven of DeeR-VLA's
eight equations were refused over `\setlength`, a spacing directive with
nothing in it to read, and the eighth over `\sideset`: for which an exact
equivalent existed, `\sum\nolimits_{X}`, and the same equation already used it
further along. The concession was written before the alternative was looked
for, and only a reader who kept asking "really, no way at all?" turned it up.

**Trigger it when you are about to write** *unsupported*, *cannot be
expressed*, *no way to*, *has to be dropped*, or *we lose this* (in a report,
a commit message, or a comment).

**Ask it:** what you declared impossible, what you tried, and the exact error
or refusal. **Expect back:** concrete candidates to test, not encouragement.
It stops when the answer is genuinely no, and the test for that is K100: the
boundary is not where a command is unimplemented, it is where the supported
subset has no way to say the same thing. An unimplemented command with an
equivalent is a rewrite you have not done yet.

### `fast-finder`: call it INSTEAD of reading the two logs

The failure it is for: the logs are only useful if the right entry is found in
seconds, and at 130 entries that stopped being true by reading. It runs
`kb.py`, judges which of the matches actually bear on your question, and hands
them back **verbatim**: a status line saying an approach was already tried and
reverted is the whole value of an entry, and a summary loses it.

**Trigger it when you would otherwise open `KNOWLEDGE.md` or `KNOWHOW.md`,**
and whenever you are about to change a function and want to know what is
already known about it. `kb.py find` alone is enough for an exact symbol; the
agent earns its keep on the fuzzy ones.

It also keeps the logs findable: `kb.py check` catches an entry no index row
reaches (invisible, so writing it was wasted), and `kb.py stale` catches an
entry naming a function the repo no longer has. Run both after Step 9.

### `referee`: call it ONCE the whole run has been gated, not per chunk

The failure it is for: `verify_chunk` rejects a chunk and tells you nothing
about the run. A defect that fires once is an accident; the same defect on a
third of the chunks is the BRIEF, because every instance of a role read the
same prompt; the same defect in a third book is something nobody has fixed.
None of that is visible from inside a chunk.

```bash
python scripts/referee.py tally  <temp_dir> --lang <lang>   # judge this run
python scripts/referee.py record <temp_dir> --lang <lang>   # and remember it
python scripts/referee.py history                           # every run so far
```

`tally` only counts and compares. **Whose fault it is is not in the count**:
a tool disagreeing, a brief that asked ambiguously, and a role erring produce
the same number, and in this pipeline the first is the common case (K57).
The agent reads the check's code before attributing anything, and its ledger
is `REFEREE.md`, searchable through `kb.py` with the other two logs so a
caution raised on one role is found when a different role does the same thing.

Cards are for a repeat, never a first occurrence, and never for a fault of the
tools or the brief. **Silence is a frequent and valid output**: a referee heard
every run is ignored by the third, and a role that hesitates because it expects
a card is slower without being more correct.

### What makes `old-man` grow

`scripts/corpus_census.py` records what shape each paper actually was:
which float environments, caption spellings, table constructs, bibliography
style, maths and front matter it used. `merge_and_build.py` writes a row at the
````

## File: README.md
upstream: https://github.com/kcy4334-lgtm/translate-book-arxiv/blob/HEAD/README.md

````text
# Translate Book: arXiv

An agent skill for Claude Code, Codex and OpenClaw that turns an arXiv paper into a translated, printable book. It reads the paper's **LaTeX source**, so equations, figures, tables and the paper's own numbering carry over. PDF, DOCX and EPUB books work too, through Calibre.

[<img src="assets/demo/03-table.png" alt="Left: Table 1 on page 7 of arXiv:2609.11801. Right: the same table on page 13 of the Korean book built from its LaTeX source, every number and every plus-minus sign unchanged.">](assets/demo/03-table.png)

<sub>Left: page 7 of arXiv:2609.11801, *Thinking with Looped Flows* (CC BY 4.0). Right: page 13 of the Korean book this skill built from its LaTeX source. Every number in Table 1, and every `±`, is the paper's. **The whole book, 31 pages: [`looped-flows_ko.pdf`](https://github.com/kcy4334-lgtm/translate-book-arxiv/releases/download/v0.5.0/looped-flows_ko.pdf).** More pages, with source and licence: [assets/demo](assets/demo/README.md).</sub>

```bash
npx skills add kcy4334-lgtm/translate-book-arxiv -a claude-code -g
```

Then ask: *"translate /path/to/paper.pdf to Korean"*. The skill recognises an arXiv preprint from its first page and asks before it downloads the source. Other agents and a manual install are under [Quick Start](#quick-start).

A PDF translator only gets what a PDF reader can recover, and equations do not survive that: `pdftohtml` breaks every formula into positioned text spans, and no option puts it back together. This skill works from the LaTeX the authors wrote.

The target language is a flag: `zh`, `en`, `ja`, `ko`, `fr`, `de`, `es`, and others. The print layout is measured against Korean, and ships with Korean typography tuned.

> Forked from [deusyu/translate-book](https://github.com/deusyu/translate-book), which grew out of [claude_translater](https://github.com/wizlijun/claude_translater) and built the agent-skill workflow: sub-agents translating chunks in parallel, manifest checks, resumable runs and several output formats from one pipeline. This fork develops the arXiv LaTeX path and the logs and advisors that ship with it.

---

## How It Works

```
arXiv paper (PDF)                    │  any other book (PDF/DOCX/EPUB)
  │  detected from the page-1 stamp   │
  ▼                                   ▼
Fetch /e-print → flatten the LaTeX    Calibre ebook-convert → HTMLZ → HTML
  │  the paper's own macros resolved from the .sty files it ships
  │  equation, theorem, section and float numbers read from the source
  │  figures rasterised from the original vector PDFs, captions attached
  ▼                                   ▼
Markdown, with $...$ math intact  ←───┘
  │
  ▼
Split into chunks (chunk0001.md, chunk0002.md, ...)
  │  manifest.json tracks chunk hashes
  │  the reference list becomes its own chunk and is copied, not translated
  ▼
Parallel sub-agents (batches of 8 by default)
  │  each sub-agent: read 1 chunk → translate → write output_chunk*.md
  │  each chunk is verified, recorded and merged as it lands
  ▼
Validate (manifest hash check, 1:1 source↔output match)
  │
  ▼
Merge → Pandoc → HTML (with TOC) → Pandoc DOCX / Calibre EPUB / Chromium PDF
```

Each chunk goes to a sub-agent with a fresh context, so a long book never fills one session and nothing gets cut off at the end.

## What it prints

The same page in each language: numbered sections, a display equation, citations, a results table and a figure. Click any page for the full-size render.

| | | | |
|:--:|:--:|:--:|:--:|
| [<img src="docs/samples/sample_en.png" width="200">](docs/samples/sample_en.png) | [<img src="docs/samples/sample_ko.png" width="200">](docs/samples/sample_ko.png) | [<img src="docs/samples/sample_ja.png" width="200">](docs/samples/sample_ja.png) | [<img src="docs/samples/sample_zh.png" width="200">](docs/samples/sample_zh.png) |
| English (source) | 한국어 | 日本語 | 简体中文 |
| [<img src="docs/samples/sample_fr.png" width="200">](docs/samples/sample_fr.png) | [<img src="docs/samples/sample_de.png" width="200">](docs/samples/sample_de.png) | [<img src="docs/samples/sample_es.png" width="200">](docs/samples/sample_es.png) | |
| Français | Deutsch | Español | |

The float label follows the language (`Figure 1`, `그림 1 (Fig. 1)`, `図 1`). Table headers and method names are translated; numbers, units and citations are not. The body font is chosen per script, and line breaking follows each language's rules.

This page was written for the repository, with made-up results, so it can be shown in seven languages without depending on any paper's licence. Its source is `tests/fixtures/sample_page.md` with one translation per language beside it, and `python tests/sample_pages.py` renders every image again with the shipped `a4-book` profile.

## Features

- **Numbers come from the paper**: equation, theorem, section, float and subfigure numbers are read from the LaTeX source and checked against the original PDF by `tests/source_probe.py`
- **The paper's own macros are resolved**: a paper's `.sty` is never `\input`, so pandoc would print `\ie` or `\parhead` as they are. `scripts/paper_macros.py` expands the definitions the paper ships: 4,099 calls across 21 papers, with nothing lost but the macro names on the six papers diffed word by word. When it cannot expand one safely it refuses and names the macro and the reason
- **The reference list is copied as is**: it becomes its own chunk, usually the largest, at 27–34% of a paper's characters
- **Parallel sub-agents**: 8 translators at a time, each with its own context, in foreground batches so the skill's pre-approved commands and writes hold for the whole run
- **Every chunk is checked before it counts**: `scripts/verify_chunk.py` compares each output with its source, the glossary it was given and the chunk it quoted
- **Consistent terms**: a glossary built before translation, a per-chunk term table, and short read-only excerpts from the neighbouring chunks for names and pronouns
- **Resumable**: SHA-256 hashes in a manifest keep stale outputs out of the merge, and a changed glossary re-translates only the chunks that used the changed terms
- **Print-ready PDF**: headless Chromium against a real `@page` box (A4, 18/18/22/18 mm, 11.5 pt), page numbers stamped afterwards because Chrome has no margin boxes. `scripts/layout.py` holds the page geometry and fonts
- **Output**: HTML with a floating TOC, DOCX, EPUB and PDF, with an optional EPUB cover, working folder and export name
- **Tests**: 2,705, standard library only, run in CI

## Growing the skill

Each paper brings LaTeX constructs the last one did not have. Four stores ship with the skill so a construct met once is handled the next time:

| | what it holds |
|---|---|
| `KNOWLEDGE.md` | What a tool actually did, with the measurement that proved it. 248 entries |
| `KNOWHOW.md` | What a way of working cost, so it is not paid twice. 44 entries |
| `REFEREE.md` | Whether a repeated failure belongs to a tool, a briefing or a role. 6 entries |
| `corpus/shapes.json` | Every LaTeX construct each paper carried, written by the build itself. 28 papers |

The census answers *"has this ever been seen?"* with a count, and lists what has never been seen, so a pattern that has never met a real example is not trusted. `tests/test_source_lint.py` fails when the corpus has met a construct nobody has classified, so a new construct is dealt with before release.

Four advisor sub-agents read the stores:

- **old-man**: before concluding a paper does not contain something, or writing a pattern whose match decides it; names the spellings and layouts the pattern would miss
- **question-monster**: after concluding something is impossible; hands back candidates to test
- **fast-finder**: instead of reading the logs; returns the few entries that bear on the question
- **referee**: once a whole run is gated; tells a tool fault from a briefing fault from a role's

### An example

From one working session:

1. `\ie` was printing mid-sentence in a finished
````
