book-translator
Skill2 starsChanged 6 months agoMITView on GitHub
Translate full-length books (EPUB) to Traditional Chinese (Taiwan) with literary tone fidelity and cross-chapter coherence, preserving EPUB structure. Use when the user says "翻書", "翻電子書", "翻譯整本書", "book translate", "bilingual epub", or gives an .epub expecting literary translation. Main session extracts an OPF spine manifest plus a per-book glossary and style anchor, then dispatches parallel subagents (each gets glossary, style anchor, and last-paragraph carryover for coherence); the first item is previewed for tone confirmation before fanning out the rest. Produces a bilingual .epub (source + translation interleaved) with manifest/glossary/state for resume. Differs from translate-book (generic PDF/DOCX/EPUB, single-language, no coherence): book-translator targets literary works, uses Opus for the style-anchor pass and Sonnet for the parallel fan-out, and gates quality before shipping. Not for short articles (use polish) or SRT subtitles (use srt).
- Reads credentials
- Installs packages
- Sends data out
1 other project uses a version of this.
Adopted by
Most recently taken up by
- WRM-FW/persona-luoxiangtheir own version, first seen Nov 16, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- WRM-FW/persona-luoxiang★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 6 are distinctive, and 17 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 60
If the command returns exit 2 or decision=="wait", call ScheduleWakeup for JSON resume_at, persist the current {book}_state.json, and …
- Distinctive: line 444
Leave them all off for production.
- Very specific: line 633
Default policy: body prose, epilogue, and English structural prose use translation files.
- Very specific: line 662
After glossary build, the main session calls translations_extra.write_nav_overrides(glossary, manifest, book_dir) to populate …
- Very specific: line 690
If the assembler aborts, the error message lists every missing idref + the fallback English label it saw — fix translations_extra.json and …
- Very specific: line 702
Use AskUserQuestion tool to present:
- Very specific: line 717
Bypass condition: if state.style_confirmed == true (resume case), skip the gate.
- Very specific: line 721
Use the Agent tool with model: "sonnet" for ch.02+ (see "Model selection discipline" below), batch size = concurrency (default 5).
- Distinctive: line 732
After each subagent returns, the main session:
- Distinctive: line 744
After each subagent returns, the main session runs:
- Very specific: line 747
If warnings contains an entry starting with AUP_REFUSED: → state.mark_aup_refused(state, chapter_id, reason=warnings[0]).
- Very specific: line 749
If warnings is empty → dispatch.extract_aligned_translation(raw, N) → state.mark_done(state, chapter_id, text).
- Very specific: line 751
If warnings contains marker misalignment OR refusal language (other than AUP) OR preface leak → retry once with the same subagent prompt.
- Very specific: line 753
If retry still fails → escalate: re-dispatch with model: "opus" (Phase 4).
- Very specific: line 754
If escalation also fails → state.mark_failed(state, chapter_id, error).
- Very specific: line 800
All 4 deterministic audits run together via audit_suite:
- Distinctive: line 884
No obvious omission (translation paragraph count vs.
- Very specific: line 891
After each subagent return + validation, the main session calls translation_log.write_log_entry(...) to persist the full prompt, raw …
- Distinctive: line 896
When an audit catches a regression in a single chapter, repair it offline without re-dispatching the subagent:
- Very specific: line 947
When this skill is invoked from within a Claude Code main session (the typical case), the main-session LLM runs the eval through the Agent …
- Very specific: line 956
After translating, save the translated text to <out_dir>/<book>/chapters/ch_NN_translation.txt.
- Distinctive: line 1080
When aligned with-table and without-table chapter translations already exist, provide all three aligned files explicitly:
- Very specific: line 1148
All paths under user-provided out_dir (default: directory of input epub).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Book Translator
Literary EPUB → bilingual EPUB translator. Optimized for novels and long-form non-fiction where tone fidelity and cross-chapter consistency matter.
Triggers
Real user phrases that should route here:
- 「翻書」「翻電子書」「翻譯整本書」「文學翻譯」
- 「bilingual epub」「book translate」「translate this novel」
- 「把 XXX.epub 翻成繁中」「跑書」
- 用戶直接給一個
.epub路徑並暗示需要文學翻譯
Not for:
- 短文 / 推文 / 一段話 → use
polish - SRT 字幕 → use
srt - PDF/DOCX 通用文檔翻譯(不需要 coherence + 單語輸出 OK)→ use
translate-book - 財報逐字稿 → use
forensic-transcript-translatorortaiwan-earnings-translator
Differentiation from translate-book
| Dimension | translate-book | book-translator |
| Input | PDF/DOCX/EPUB | EPUB only |
| Subagent model | Sonnet | Sonnet 4.6 (default fan-out) / Opus 4.7 (ch.01 anchor + escalation) / local Ollama (opt-in) |
| Output | 翻譯版 (single language) | Bilingual (source + translation interleaved) |
| Coherence | None | Glossary + style anchor + carryover + spot-check |
| Quality gate | None | Cross-modal eval (Gemini 2.x Pro + GPT-4o, avg ≥ 8.0) |
| Resume | None | state.json |
| Domain | Generic | Literary (tone-critical) |
Translation provider (engine)
The skill supports two providers:
- Anthropic (default for online quality-first) — Claude Code subagents
(Opus 4.7 anchor + Sonnet 4.6 fan-out), parallel
concurrency=5. Best quality; spends CC subscription quota. Triggered by the main workflow (see "Workflow" section below). - Anthropic provider automatically uses the shared quota gate before Opus/Sonnet
fan-out. The user does not need to say
agent-orch:/Users/fredchu/bin/agent-orch quota check --provider claude --threshold 85 --on-error fail-open --json. If the command returns exit 2 ordecision=="wait", callScheduleWakeupfor JSONresume_at, persist the current{book}_state.json, and resume from completed chapter outputs after waking. Ifdecision=="probe_failed", retry afterretry_at/retry_after_seconds; ifextra_usage.stateisdisabled/exhausted, reduce fan-out concurrency or switch to offline provider instead of waiting for reset. omlx (default for offline) — local omlx server at
localhost:8090, sequential MLX inference on Apple Silicon Metal. Default model:Qwopus3.6-27B-v2-MLX-4bit(Jackrong, Claude Opus 4.6/4.7 TraceInversion distilled on Qwen3.5-27B; 14 GB, ~12 t/s, ~0.84 min per 3000-char chunk). Quality-first: on a full-chapter human read-through it was judged clearly better than the 35B on prose rhythm and 台灣 usage, and it ran the chapter with 0 retries / 0 dropped paragraphs where the 35B needed 2 retries plus a single-paragraph fallback. A 470K-char book takes ~3.2 h.Qwen3.6-35B-Heretic-4bit(Qwen3.6-35B-A3B, 3B-active MoE; 20 GB, ~43 t/s) is the speed alternate at ~4x faster (~0.8 h for the same book) — use it for drafts via--omlx-model Qwen3.6-35B-Heretic-4bit.enable_thinking:Falseis required and OmlxProvider sets it for both. Engine auto-selected when--engineomitted.Default history — read before "optimising" this again. 2026-06-25 promoted the 35B on a ~5x throughput win plus a machine register score from a single-chapter spot check. 2026-08-09 reverted it: a reader compared full chapters and called the 35B's output clearly worse. Throughput and automated register scores did not predict what a native reader caught in minutes. Do not re-promote on benchmark numbers alone.
See
2026-06-25-heretic-35b-a3b-local-translation-speedup.md(the spot check that oversold the 35B) and2026-05-23-local-translation-acceleration-research.md.- Ollama (alternate offline) — local Ollama server at
localhost:11434, sequential (single GPU via llama.cpp). Useful for GGUF-only models (Hy-MT2, translategemma) when omlx is unavailable. Alternates:translategemma:12b(~1h27m E2E, fast but Simp leak high before TRADITIONAL_CHINESE_ENFORCEMENT prompt);hy-mt2:7b(~2h27m E2E, recursive split on 2-3 large chapters). See2026-05-23-five-way-quality-comparison.mdfor the full matrix that motivated the move off Ollama defaults. Cloud vLLM(Vast.ai/RunPod,2026-09-04 起) — 沒有 Apple Silicon、或想比本機快 3–5 倍時,
scripts/cloud_llm.sh在雲端 GPU 上用官方 vLLM 映像開伺服器,翻譯器照走 omlx 引擎,只是--omlx-host指到雲端、--omlx-api-key帶金鑰。不上傳程式、不走 SSH:只開 8000 埠, 用 vLLM 的--api-key擋公開埠。翻完砍機(trap 保證、回查確認)。 預設--profile int4=XReyRobert/Qwopus3.6-27B-v2-GPTQ-Pro-v1(18.7 GB,跟本機 MLX 4bit 同級) 配 RTX 5090(Vast 約 0.40 美元/小時);「這本要書面一點」用--profile fp8=作者的Jackrong/Qwopus3.6-27B-v2-FP8(30.9 GB,要 ≥40 GB 卡,預設 L40S 約 0.80)。fp8 不是「品質比較好」,是「語域不同」(2026-09-10 實讀)。 同一章、同一款卡、同樣 prompt 與後處理,唯一變因是量化精度, 兩版逐字相似度 84.3%——低於「同一版本重跑一次」的 88.2%,所以差異是真的不是噪音。 但讀者的判斷是各有優缺點、適合不同內容: int4 用詞白話口語、句子較短;fp8 用詞精練書面,有「嚴謹、正式」的感覺。 所以這是按書選語域,不是「重要的書就升級」。 成本:fp8 每本貴約 18%(同價格、同開機時間歸一化。第四次更正,2026-09-10 真機)。
前三次都用探針選到的 N 算,而探針本身在低估:它選 16,三級持續負載實測 安全上限是 32(16/24/32 → 270.5/342.4/414.9 tok/s,各 160/240/320 筆零錯誤)。 用 N=32 重算:SGLang fp8 每本 0.153 對 vLLM int4 N=32 的 0.130 是 1.18 倍。 「貴 83%(1.8 倍)」那版是用被錯誤閘門壓到併發 8 算的,整條錯。
這個數字改過三次,第三次改對了才是現在這句(spec-05,2026-09-10): 第一版「貴 31%」是拿併發 16 算的;第二版改成「貴 83%(1.8 倍)」,理由是探針的 「跑飛餘裕」門檻把 fp8 壓到只剩併發 8。第二版的門檻本身是錯的——它算門檻用的 120 秒逾時,翻譯器實際從來沒用過(翻譯器真正的逾時預設是 1800 秒,兩者差 15 倍, 三席都以為那個 120 是真的,直到有 worker 動手接線才發現對不上)。改成不靠這個 不存在的逾時之後,fp8 拿得到併發 16,貴的比例退回接近第一版,但理由完全不同—— 不是「原本猜對了」,是「原本的推理鏈跟原本的答案剛好都錯在同一個方向」。 細節見 CHANGELOG「Corrected — the v1.1.0 concurrency probe's absolute threshold never matched reality」那條。
同族教訓:2026-06-25 曾用自動化語域評分把 35B 升成預設,2026-08-09 讀者讀完一章推翻。 這是同一族錯誤的第三次:自動化的數字說不出讀者讀到的東西,這次連自動化的數字 自己內部都對不上。 機器挑選、IP 排除、停滯偵測都沿用 srt-skill 的
vast_instance_lib.sh/runpod_pod_lib.sh。機器記憶(2026-09-10 起,沿用 bookcast,只用於 Vast):跟 bookcast 租同一個 Vast 機器池,好壞紀錄共用一份 sqlite3(
CLOUD_LLM_MACHINE_MEMORY,預設~/.local/state/bookcast/vast-machine-memory.sqlite3),bookcast 不用改一行。 挑報價分三層、額度各自獨立:白名單(近期成功機,CLOUD_LLM_WHITELIST_TRIES預設 2) → 排除有效黑名單的一般市場 → 若一般市場曾被黑名單限制過,再開一次無過濾的緊急市場 (後兩層各自都是完整的CLOUD_LLM_MAX_OFFER_TRIES,預設 3,不共用同一個池)。 跨 repo 執行期相依,一律軟性失敗:bookcast 模組不在、import 失敗、資料庫壞掉都只印 警告、照常走一般搜尋,絕不會讓租機器停下來。壞機器的machine_id在 pick_offers 階段 拿不到,只有offer_id——照抄 bookcast 的做法,在 create 之後、terminate 之前補抓。 只有腳本自己die()觸發的結束才記失敗;使用者 Ctrl-C 不算機器壞掉。成功則在伺服器就緒、 thinking preflight 通過時就記,不等一整本書翻完(書翻失敗多半跟機器好壞無關)。 這一輪沒動:bookcast 自己的雲端偵測器(cloud_detector.py)仍然只認bookcast-前綴,看不到 book-translator 開的機器——那要改另一個 repo,且它只推通知不砍機, 不能取代「跑完回查確認」,留在 OPEN-ITEMS。併發(2026-09-10 起,雲端預設;判準 2026-09-10 spec-05 起換過一次):本機 omlx 單一 GPU 維持循序。雲端 vLLM/SGLang 由
cloud_llm.sh預設帶--concurrent-chapters --max-concurrent-requests N;直接跑 driver 時要同時加這兩個旗標, 前者開跨章排程、後者控制全書總在途 request 上限。server 以最高候選 32 開機, client 則由自適應探針從最小的候選往上量,選到不再划算為止;不會膨脹成 「章數 × 塊數」的無界 fan-out。舊表(16/24/32 的「120 秒餘裕」欄)整欄作廢——那個 120 秒逾時翻譯器從來沒真的 用過,見 CHANGELOG「Corrected — the v1.1.0 concurrency probe's absolute threshold never matched reality」;tok/s 跟每本執行費那幾欄是真量測,還能參考,只是不能再拿「餘裕」 那欄的百分比做任何判斷。
v1.2.0 起的判準(2026-09-10 真機重做,舊的「飽和要贏上一級 10%」已廢):
舊判準用「該波總 token ÷ 該波牆鐘」算增幅,而牆鐘由該波最長那一筆決定。 併發越高越容易抽到長塊 → 越容易被誤判成飽和。真機實測:N=24 實際 +26.6%, 舊量法只算出 +3.4% → 早停選 16,藏掉 53% 效能(32 比 16 快 53%)。
- 量法改成閉環中段窗口:每級 N 槽持續補送 T 秒(T=max(60, 3×中位延遲)), 一筆完成立刻補一筆讓在途數整段維持 N,只算中段窗口內完成的 token ÷ 窗口長。 進場坡在窗口前、沒有尾巴、窗口內在途數恆為 N。
- 落後者:不變,最長延遲不超過該波中位的 3 倍。
- 門檻改成不對稱:早停一次藏掉 53%,多爬一級只多約一分鐘——代價不對稱, 門檻就不該對稱。安全閘過就繼續爬;連兩級都掉超過 5% 才停; 選整段吞吐最好的那級,不一定是最高 N(「更高實際更差」的保護還在)。
- 邊際效率門檻:新最好要 > 最好 × (1 + 0.2 × (N/N_best − 1))。 真機六級效率 1.10/0.37/0.70/0.37/0.07——真級最低 0.37、排隊高原 0.07, 中間空一大段,門檻 0.20 是從資料推的。沒有這道會選到排隊高原: 真機第一次跑新規則就選了 48(伺服器上限 32、多的在排隊), 換到 3.5% 吞吐卻付出中位延遲 +40%。
- KV 夾(算術事實,零成本):候選 N ≤
max_total_num_tokens÷ 3700。 真機 129,742 → 35,所以 48 根本不該進候選。前者是統計判斷,後者是算術。 - 🔴 探針的值只用來排序與選 N。成本與配方數字一律取自 10×N 持續負載—— 探針對持續負載系統性高估約一成(塊對塊 +9%;含接縫的全書負載約 +15%)。
- 逾時不再是探針的輸入,是探針的輸出:
derive_timeout()用「選中那一級」自己量到的 數字算——max(3 × 那一級最長延遲, max_tokens ÷ 那一級平均單筆速度 ÷ 0.8)——cloud_llm.sh把這個算出來的秒數直接餵給翻譯器的--timeout,兩邊天生同一個來源, 不是兩個地方各自維護同一組數字(那正是這次要修的洞)。 - 預設 16 只在探針整個跑不起來時當退路,理由改成「唯一量過的卡上、品質訊號全 0 的 最小值,保守起見沒量過的卡也預設用它」,不再跟任何百分比餘裕掛勾——理由變了, 數字沒有跟著拉高。
每次結果寫入 run 目錄的
adaptive-concurrency.json(卡名只記錄、不參與決策)。明傳CLOUD_LLM_CONCURRENCY時探針仍照跑留證據,client 尊重明傳值;高於安全值會明顯警告。術語表是併發的前提,不是加分項。 開併發前先建立並人工確認
<book_dir>/spec_terms.json。八趟 Mind-Gut 實測:有術語表的三種模式,人名都只剩單一形態, 次數為 61/61/60;沒有術語表的五趟中,四趟出現三種形態,而併發路徑最分散, 另冒出第五種形態「艾蘭娜」13 次。機制是章內並行把接續上下文改成原文,各塊會獨立 決定人名譯法;跨章並行又增加獨立邊界。driver 偵測到任一併發旗標開啟但沒有可用術語表時, 會在 stderr 明顯警告但不阻擋,使用者仍可自行承擔一致性風險繼續。章內接縫預設做 seam repair:重翻邊界第一段,取回上一塊真正譯文的上下文;可用
--no-seam-repair關閉。跨章並行時跨章 carryover 為空,這是以吞吐換取章界上下文的明示 取捨。細節與守衛見CHANGELOG.md的 concurrent translation 條目。
Cloud mode — triggers + workflow
Triggers: 「用 vast 翻 X.epub」「上雲翻」「用 runpod 翻書」「cloud translate」→
(「用 colab 翻」「Colab A100 翻書」→ --provider colab,見下方 Colab 小節)
scripts/cloud_llm.sh --provider vast -- --book /path/X.epub --out /path/translations/
scripts/cloud_llm.sh --provider runpod -- --book /path/X.epub
scripts/cloud_llm.sh --profile fp8 -- --book /path/X.epub # 這本要書面、正式一點
scripts/cloud_llm.sh --keep -- --book A.epub # 翻完不砍;下一本用 runs/<id>/endpoint.env
scripts/cloud_llm.sh --stop runs/cloud-llm-<id> # 砍掉 --keep 的那台--後面就是translate_book_ollama.py的參數(多本一次給多個--book也行)。- 憑證:
VAST_API_KEY/~/.config/vastai/vast_api_key;RUNPOD_API_KEY/~/.config/runpod/api_key。 - 錢的守衛:
CLOUD_LLM_BOOT_WAIT_MIN(25,拉映像+下載模型)、CLOUD_LLM_BOOT_STALL_MIN(6)、CLOUD_LLM_MAX_HOURS(2026-09-10 起隨 --book 本數放大:6 小時+每多一本+0.5 小時, 一本仍是 6、兩本 6.5、13 本封頂 12 小時;超過 12 小時自動放大上限直接 die,不悄悄放大, 要明傳CLOUD_LLM_MAX_HOURS才會租機;明傳一律優先,本數算不出來也維持 6。 看門狗超時送 TERM 讓 trap 砍機——這是本機端的 sleep+kill,不是遠端自砍: 本機這個 shell 死了(睡眠、斷線、關終端機),遠端機器就沒人管,額度加再多小時 都不會讓遠端自己停下來)。收屍:bash ~/dev/srt-skill/scripts/vast_reap.sh/runpod_reap.sh。 - 推論 server 可用
CLOUD_LLM_ENGINE=vllm|sglang選擇;兩邊各自組原生參數,不用互塞不相容旗標。⚠️ 預設的 int4 GPTQ 模型在 SGLang 上載不起來,但主要責任在 checkpoint 不在 SGLang (2026-09-10 真機試過 + 查上游)。 真因:那份 GPTQ checkpoint 的量化工具跳過了
in_proj_a/in_proj_b(48 個線性注意力層各 2 個,共 96 個),卻沒寫進設定檔的排除規則—— 設定裡的dynamic只排了 embed/lm_head/mtp/norm/vision。 所以 SGLang 照設定把那些層當量化層建,找不到qweight→ 96 次not found in params_dict→ 再對沒載到的 96 寬層做 marlin 重打包 → 崩。 SGLang 那邊的責任比想像中大:它只信設定不看權重,而且那個洞今天還開著—— 上游#22618提過修法(檢查ignore清單),但那個 PR 從來沒被合併 (merged: false,被機器人以「作者閒置 PR 超過軟上限」自動關掉)。 實查 v0.5.19 的qwen3_5.py:連modelopt_fp4的 guard 都沒有。 vLLM 走得過,但那只代表 vLLM 對這種不一致比較寬容,不代表 checkpoint 沒問題。 要用 SGLang 就用 fp8 版(它的modules_to_not_convert有 882 條逐層明列, 已實測載入成功)。細節見 CHANGELOG 2026-09-10。讀 log 時注意:
Using gptq_marlin kernel不代表通過,那只是宣告要用 marlin, 真正的檢查在重打包時才跑。 SGLang 強制--reasoning-parser qwen3。兩個引擎在正式翻譯前都會送 thinking preflight,確認enable_thinking:false生效、content 無 think tag、reasoning_content為空,否則立即砍機。 - 在 Claude Code 裡跑長書請放背景並掛監看;Ctrl-C 會砍機(那是刻意的)。
- Colab(2026-10-12 起,
--provider colab):預設 A100,扣 Colab 運算點數(A100 每小時約 5.3 點)不另外付錢。 前提:uv tool install google-colab-cli並在終端機跑過一次colab usage完成登入;SSH 金鑰要 ed25519/ecdsa。 vLLM 開機後 pip 裝(約 1 分鐘),端點是常駐 SSH 的本機埠轉送,所以只支援 vllm、不支援--keep。 帳號同時最多兩台;查colab sessions、手動關colab stop -s <名>。砍機前會把遠端boot.log拉回 run 目錄的colab-boot.log。實測開機到就緒約 8.5 分鐘;坑的細節見 wiki〈Colab CLI 無人值守租用 GPU 的實務〉。 速度(2026-10-12 Mind-Gut 真機):A100 比 Vast 5090 快約 1.5 倍,整本 Mind-Gut 用併發 48 翻完 4.9 分鐘。 Colab 預設併發 48(不交給探針:探針的邊際效率門檻在 A100 上永遠停在 16);48/56/64 吞吐差不多, 再往上沒用。要改用CLOUD_LLM_CONCURRENCY。 - 09-04 真機:台灣 5090(0.356 美元/小時)從開機到 vLLM 就緒 19 分鐘(拉 10 GB 映像+下載 18.7 GB 模型+初始化), 固定開銷約 0.12 美元;之後翻譯 5 章結構測試檔 0.3 分鐘。RunPod 路徑只有替身測試,還沒真機跑過。
Offline mode — triggers + workflow
Triggers (main session routes here when the user says):
- 「離線翻 X.epub」「local translate X.epub」「translate offline X.epub」 → omlx + Qwopus3.6-27B-v2-MLX-4bit (default, quality-first)
- 「快一點」「先出草稿」「draft」 →
--omlx-model Qwen3.6-35B-Heretic-4bit(~4x faster) - 「用 omlx 翻 X.epub」 → same default path
- 「用 hy-mt2:7b 翻書 X.epub」「用 translategemma:27b 翻書 X.epub」「ollama 翻書 X.epub」 → ollama path with specified model (alternate / legacy)
- 「批次翻 X.epub Y.epub」「翻這幾本 ...」 → multi-book driver 同個 path
- Any phrase that names an ollama model + a book path → ollama path
Driver — main session runs (omlx default, no engine/model flag needed):
python3 ~/.claude/skills/book-translator/scripts/translate_book_ollama.py \
--book /path/to/X.epub \
--out /path/to/translations/
# expands to: --engine omlx --omlx-model Qwopus3.6-27B-v2-MLX-4bitMulti-book batch (2026-05-23 ship) — 一次傳多本,driver 內序列翻譯, per-book error containment:
python3 ~/.claude/skills/book-translator/scripts/translate_book_ollama.py \
--book /path/A.epub /path/B.epub /path/C.epub \
--out /path/to/translations/Final summary 印每本 success/failed + duration。
For ollama path (alternate):
python3 ~/.claude/skills/book-translator/scripts/translate_book_ollama.py \
--book /path/to/X.epub \
--engine ollama --ollama-model hy-mt2:7b \
--out /path/to/translations/The driver runs end-to-end: extract → sequential per-chapter translate (with
Phase 1 [[PARA_N]] marker enforcement + 1 retry on misalignment) → offline
post-processing → assemble → 4 audit gates. Progress + state.json checkpointing
is per-chapter, so a killed/interrupted run resumes on the next invocation.
Offline post-processing (scripts/offline_postprocess.py) recovers the quality
the skipped glossary/nav build would have provided, since the offline path has no
glossary:
- Simplified→Traditional — at write time, sentences delimited by
。!?;:, newlines, and ASCII.!?are run through openccs2twonly when they contain an unambiguous Simplified character from opencc'sSTCharacters.txt(plus the known mainland form着). A character does not trigger when it is one of its own Traditional candidates, so valid Taiwan forms such as范are left alone. This sentence gate matters because evens2twcan corrupt correct Traditional prose (肥皂劇→肥皂剧,只能→隻能);s2twpis still forbidden because its additional vocabulary table is more aggressive (循环→迴圈,调用→呼叫,窗口→視窗). A small Taiwan-form trigger exclusion set and the existing_PROTECTED_TERMSshields reduce collateral conversions. Ambiguous mainland forms such as某种can be missed by design (measured near 3% of residual conversion hunks). The driver validates and logs the trigger-set size before extraction/GPU work, refusing to start if opencc orSTCharacters.txtis unavailable; the helper itself remains a warning-only no-op so a late chapter write is not destroyed. - Character-name coherence — without a glossary the model drifts between transliteration variants (瑪德琳 vs 梅德琳); a conservative pass merges minority variants (length ≥ 3, free-standing, dominated ≥ 4×, never two real names) into the dominant form before assembly.
- Acronym collapse — after the first 「人工智慧(AI)」, later 人工智慧 become bare
AI. Same cross-chunk cause as gloss dedupe: every chunk thinks it is the term's first mention (measured: 人工智慧 x10 in one chapter, in two independent runs). The Chinese rendering is learned from the surviving gloss, so a book that writes 「人工智能(AI)」 collapses that instead. Runs after gloss dedupe, which leaves exactly one gloss to learn from. - Inline-gloss dedupe —
OFFLINE_STYLE_RULESasks for 「中譯(English)」 on a term's first mention, but the model sees one chunk at a time and has no memory of earlier chunks, so it re-glosses the same term in every chunk that mentions it (measured: 104 glosses for 78 unique terms in one chapter). A book-wide pass keeps the first occurrence and strips the rest. Do not try to fix this in the prompt — cross-chunk state is not something the model has. - Bilingual ToC — nav_overrides are populated from each heading-led chapter's translated title so the table of contents renders bilingual.
The offline prompt also carries dispatch.OFFLINE_STYLE_RULES (structural rules
only: relative-clause rewriting, no 「,這些X」 anaphora, 台灣 usage, inline glosses,
meaning preservation). Never add a sentence-length rule there — see the
comment block above that constant for the measurements showing why a 「超過 40 字
就斷句」 rule wrecked the prose while scoring best on the length metric.
Expected runtime for a 23-chapter / ~150K-char book on M1 Max 32GB (measured 2026-05-23 on The Next Renaissance):
| Engine + Model | E2E duration | Marker align | Simp leak | Quality (5-dim) |
| omlx + Qwopus3.6-27B-v2-MLX-4bit (default, 2026-08-09) | 2h13m | 23/23 = 100% | 0.9% | ★★★★★ preferred on human read-through |
| omlx + Qwen3.6-35B-Heretic-4bit (speed alternate) | ~25-30min (est, ~5x) | 100% | 0.3% | ★★★☆☆ flatter prose, more 中國用語 |
| ollama + translategemma:12b | 1h27m | high | needs new prompt enforcement | ★★★☆☆ |
| ollama + hy-mt2:7b | 2h27m | moderate | ~100% Trad | ★★★☆☆ |
| ollama + translategemma:27b | 3-4h | similar to 12b | similar | ★★★☆☆ (12b 全面超越) |
The 5-dim "Opus tier" score was wrong about the 35B. It came from a model-fit-scout spot check (ch9 of The Next Renaissance, 123 paras): Heretic-35B 43.2 t/s vs Qwopus-27B-v2 8.0 t/s (5.4x), both 100% marker-aligned, scored at register parity. On a full chapter of Superagency with a reader comparing side by side, the 35B was rejected: flatter rhythm and noticeably more 中國用語. Measured on that chapter (106 paras, rules held constant): the 27B produced 45 inline 中譯(English)glosses and 47 mainland usages without style rules, versus the 35B baseline's 58 glosses and 0 mainland usages — but with the rules applied the 27B lands at 104 glosses / 2 mainland usages and reads better. Both models need the style rules; only the 27B rewards them.
Lesson for whoever tunes this next: a single-chapter automated register score plus a throughput number is not enough to move the default. Have someone read a full chapter of both.
Quality positioning:
- omlx + Qwopus3.6 ≈ matches Opus 4.7 register tier (sample diffs in chunk-size punch only, see _outputs research file)
- ollama + hy-mt2:7b / translategemma:12b: 0.7-1.0 lower on 5-dim eval; usable for drafts / offline reading, not interchangeable for literary fiction.
Single-chapter spot check (omlx default; no assemble, no audit):
python3 ~/.claude/skills/book-translator/scripts/translate_chapter_cli.py \
--book /path/to/X.epub --chapter N \
--out runs/spot-check/ --validate-markers
# expands to: --engine omlx --omlx-model Qwopus3.6-27B-v2-MLX-4bitCross-model benchmark (multiple models, side-by-side first paragraphs):
python3 ~/.claude/skills/book-translator/scripts/run_benchmark.py \
--book /path/to/X.epub \
--models hy-mt2:7b,translategemma:27b \
--chapters 5,6 \
--out runs/benchmark/Installing omlx + Qwopus3.6 (new default offline path)
omlx is the multi-model MLX inference server for Apple Silicon. Install via Homebrew tap (one-time):
brew install jundot/omlx/omlx
brew services start jundot/omlx/omlx
# verify: curl http://127.0.0.1:8090/v1/models | jq '.data[].id'Download the default Qwopus3.6-27B-v2-MLX-4bit (~14 GB) into ~/.omlx/models/; the
~20 GB Qwen3.6-35B-Heretic-4bit speed alternate is optional
(use HF_HUB_DISABLE_XET=1 — the xet transfer path stalls mid-download on large
MLX repos):
HF_HUB_DISABLE_XET=1 hf download froggeric/Qwen3.6-35B-A3B-Uncensored-Heretic-MLX-4bit \
--local-dir ~/.omlx/models/Qwen3.6-35B-Heretic-4bit
# omlx auto-scans on next request; or POST /admin/api/models/Qwen3.6-35B-Heretic-4bit/loadFallback (smaller RAM footprint, ~14 GB):
hf download Jackrong/Qwopus3.6-27B-v2-MLX-4bit \
--local-dir ~/.omlx/models/Qwopus3.6-27B-v2-MLX-4bitchat_template_kwargs.enable_thinking=false is mandatory for translation; the
OmlxProvider sets this by default, and it works on both the Qwopus default
(via its fixed chat template) and the Qwopus fallback. Manual API call:
curl -X POST http://127.0.0.1:8090/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwopus3.6-27B-v2-MLX-4bit",
"messages": [{"role":"user","content":"翻譯:Hello"}],
"chat_template_kwargs": {"enable_thinking": false}
}'Acceleration toggles (dflash_enabled / mtp_enabled / specprefill_enabled)
do not help on M1 Max + 27B + translation — verified 2026-05-23 across 12 paths
(see wiki/_outputs/2026-05-23-local-translation-acceleration-research.md).
Leave them all off for production.
Installing the Hy-MT2 models (alternate offline path)
Hy-MT2 GGUFs have a broken auto-generated chat template on ollama 0.24. Install via the project's pre-built Modelfiles (one-time):
ollama pull hf.co/tencent/Hy-MT2-1.8B-GGUF:Q4_K_M
ollama pull hf.co/tencent/Hy-MT2-7B-GGUF:Q4_K_M
ollama create hy-mt2:1.8b -f ~/.claude/skills/book-translator/scripts/modelfiles/Modelfile.hy-mt2-1.8b
ollama create hy-mt2:7b -f ~/.claude/skills/book-translator/scripts/modelfiles/Modelfile.hy-mt2-7btranslategemma models work as-is: ollama pull translategemma:{4b,12b,27b}.
Provider abstraction lives in scripts/providers/; new engines plug in by
subclassing TranslationProvider and registering with provider_factory().
Contract
Given an EPUB and target language (default: 台灣繁體中文), this skill:
- Reads the entire book, extracts a glossary (characters / places / terms / chapter titles / style anchor).
- Auto-populates per-book nav overrides from glossary chapter titles.
- Translates chapter 1 in the main session as the style sample.
- Asks the user to confirm tone / edit glossary before fan-out.
- Dispatches parallel subagents (Sonnet 4.6 default, concurrency 5; Opus 4.7 on validation escalation) to translate remaining
translatespine items — each receives glossary + style sample + last-paragraph carryover. - Assembles a full-fidelity bilingual EPUB from the full OPF spine: original XHTML paths, OPF idrefs, CSS, fonts, images, class names, and internal href targets are preserved; Traditional Chinese paragraphs are inserted after English text blocks.
- Runs structural QA (
structural_audit.py), bilingual coverage QA (bilingual_coverage_audit.py), href resolution QA (href_resolve_audit.py), translation placeholder/length QA (translation_quality_audit.py), and a separate translation spot-check pass (random 5 paragraphs + character name audit) before shipping. - Crash-safe: every step persists to
{book}_state.json; re-running resumes from last completed chapter.
Architecture
Main session (Claude Code, Opus 4.7 for ch.01 anchor)
├── 1. extract_epub.py book.epub → full OPF spine manifest v2 (deterministic)
├── 2. glossary build (LLM call in main session) (latent)
│ └── reads full book → glossary.json
├── 2.5. populate translations_extra nav_overrides (deterministic)
├── 3. translate ch.01 in main session → style_sample (latent)
├── 4. INTERACTIVE PREVIEW GATE (user-in-loop)
│ └── print ch.01 preview → user [confirm | edit glossary | edit style]
├── 5. Agent dispatch ch.02 .. ch.N (concurrency 5) (parallel subagents, Sonnet 4.6 default)
│ └── each gets: chapter + glossary + style_sample + carryover
├── 6. assemble.py → bilingual.epub (deterministic)
├── 7. structural_audit.py → spine/image/state completeness (deterministic)
└── 8. spot-check (random 5 paragraphs + name audit) (latent)Shared deterministic modules
Cross-cutting deterministic logic lives in named modules; all read/write call sites delegate so behaviour stays consistent across extract, dispatch, assemble, and audits.
Content / EPUB I/O:
scripts/content_blocks.py— canonical "what counts as a paragraph".TEXT_TAGS,BLOCK_TAGS,walk_text_nodes,extract_blocks,extract_paragraphs,strip_non_content,TextBlock/ImageBlock. Used bydispatch.html_to_paragraphs/dispatch.html_to_blocks(thin wrappers),assemble._text_nodes_for_bilingual,bilingual_coverage_audit.translation_quality_auditaudits already- markedclass="src"pairs, not raw paragraphs — intentionally outside.scripts/epub_reader.py— EPUB-zip reader (context manager).EPUBReader,OPFPackage,ManifestItem,find_opf_path. Tolerant of missingcontainer.xmlAND missing.opf(returnsNone). Used byextract_epub.py,bilingual_coverage_audit.py,translation_quality_audit.py.scripts/manifest.py— manifest v2 normalization + persistence.SpineEntrydataclass,normalize_entries(manifest),chapters_from_spine,entry_original_path,load,save. Consolidates v2 spine reading + legacychapters[]backfill that was previously duplicated in extract / assemble / structural_audit / state.
Persistence:
scripts/translations_extra.py—translations_extra.jsonowner.TRANSLATIONS_EXTRA_FILENAME,load,save,write_nav_overrides.glossary.write_translations_extra_nav_overridesis now a back-compat alias.scripts/glossary.pygainsload_glossary+ the moved register lookupREGISTER_HINTS_PATH/resolve_register_override/resolve_register_rules(previously in dispatch.py).scripts/state.py—ChapterEntrydataclass owns theoutput_strategymutation invariant. The four mark_* helpers (mark_done/mark_failed/mark_source_ready/mark_dropped) delegate so the invariant is preserved uniformly. State.json on disk shape unchanged.
Assemble pipeline (split from the former 770-line god module):
scripts/assemble.py— thin orchestrator.assemble(book_dir, out_path)sequences manifest load → spine entries → preflight → per-entry bilingual rewrite → nav build → archive write.scripts/bilingual_rewriter.py—insert_bilingual(src_html, entry, translations)does per-paragraph English/中文 interleaving.STRUCTURAL_LABELS_ZH_TWlives here.scripts/nav_builder.py—build_nav_xhtml,nav_path,patch_toc_ncx,missing_nav_zh_warnings,source_ncx_path. Generates the bilingual nav and patches NCX for legacy readers.scripts/archive_writer.py—write_from_source_archive(default, overlays rewritten files onto source EPUB) andwrite_standalone_archive(fallback when source archive isn't accessible).scripts/opf_builder.py—build_minimal_opf+fallback_opf_pathfor the standalone path.
Audit interface:
scripts/audit_result.py— canonicalAuditResult(name, status, failures, details)dataclass +.passed/.format_lines(). Replaces the divergent shapes that the 4 audits previously returned.scripts/audit_suite.py—run_all(source, output, book_dir),all_passed,format_summary. CLI:python3 -m scripts.audit_suite ...orpython3 scripts/audit_suite.py ....- Each audit module retains its legacy
audit(...) -> tuple[bool, list[str]]for back-compat, plus arun(...) -> AuditResultthat audit_suite calls.
4 Coherence Mechanisms
- Glossary injection — main session reads full book → JSON of characters / places / terms; every subagent prompt receives it.
- Style anchor — chapter 1 translated in main session becomes the reference style; every subagent prompt includes the first 500 chars as anchor.
- Last-paragraph carryover — each subagent gets the last 200 chars of the previous chapter's translation so the opening flows.
- Spot-check pass — after all chapters complete, main session samples 5 random paragraphs and cross-references character name appearances against glossary. Mismatches → flag, do not auto-fix (avoid silent corruption).
Model selection discipline
| Stage | Model | Why |
| Glossary build (full-book read) | Sonnet 4.6 | Throughput; the LLM is summarizing structured fields, not producing literary text. |
| Ch.01 style sample (main session) | Opus 4.7 | The translation here becomes the style anchor for every subsequent subagent. Pay for quality once. |
| Ch.02..ch.N fan-out (subagent batch) | Sonnet 4.6 (default) | Bulk throughput. The style anchor + glossary + carryover constrain Sonnet's register adequately for business / popular-science / general non-fiction books. |
| Escalation on validation reject | Opus 4.7 | Retry with the same prompt but better model when Sonnet fails marker alignment, leaks persona, or produces refusal language (non-AUP). |
| Spot-check pass (random 5 paragraphs) | Sonnet 4.6 | Lightweight read; main session calls inline. |
Why not Opus everywhere? Token cost. Bocky's 9-book实战 baseline (Opus
default) ran at ~12h / book because 100+ chunks × Opus eats the 5h Anthropic
quota window 2-3 times per book. Sonnet for fan-out cuts the token cost ~5x
without dropping below the literary-tone-fidelity floor for our scope
(business / popular-science). For literary fiction or
philosophy-heavy texts (Taleb / Mandelbrot register), override to Opus default
via model: "opus" on the Agent dispatch.
How to override per book: the orchestrating session sets model: on the
Agent tool call. There is no config file — model selection is a per-dispatch
decision the main session makes based on the book's domain and the user's
quality preference for that batch.
Workflow
Step 1: Collect parameters
book_path— required, must be.epubtarget_lang— defaultzh-tw(台灣繁體中文; use 台灣用語 not 大陸用語)style_hint— optional user override of style anchorconcurrency— default 5; max 10 (CC quota safety)out_dir— default same dir as input
Step 2: Extract full OPF spine
python3 {baseDir}/scripts/extract_epub.py "<book_path>" --out "<out_dir>"extract_epub.py delegates META-INF/container.xml lookup + OPF parsing to
scripts/epub_reader.py (shared with the audit scripts) and manifest v2
spine normalization to scripts/manifest.py (SpineEntry +
normalize_entries + chapters_from_spine). The rest of the extraction
pipeline (asset copy, XHTML mirror, manifest.json write) stays in
extract_epub.py.
Produces <out_dir>/<book_stem>/source.opf, verbatim asset directories
(css/, fonts/, images/), original XHTML copies under xhtml/,
compatibility files in chapters/item_NNN.html, and manifest.json.
The manifest source of truth is spine[], not chapters[]. Every original OPF
spine item is represented unless it is explicitly drop_explicit with a
non-empty reason. The compatibility chapters[] list contains only
translate items for current dispatch tooling.
Each spine entry records the original EPUB package path (original_path) and
original OPF idref (original_idref) so assembly can emit the source layout
instead of synthetic chapter filenames.
Output strategies:
translate— requireitem_NNN_translation.txt; assemble bilingual source / translation interleaving.source_only— no translation file required; preserve source content in the output spine.nav_generated— omit source nav and regenerate EPUB nav/NCX from represented output spine.drop_explicit— omit only with a visible, non-empty reason.
Default policy: body prose, epilogue, and English structural prose use
translation files. Structural pages may be kept source_only only when they
are genuinely image-only or deliberately listed in
translations/source_only.json; the assembler no longer invents placeholder
translations for missing paragraphs. The source nav is replaced with a
deterministic bilingual nav at the original nav path.
Step 3: Build glossary
Main session reads the full book content (concatenate chapter texts), then makes one inline LLM call to extract characters / places / terms / style_anchor. Result written to <out_dir>/<book_stem>/glossary.json.
Schema:
{
"characters": {"Napoleon": "拿破崙", "Snowball": "雪球"},
"places": {"Animal Farm": "動物農莊"},
"terms": {"Beasts of England": "英格蘭的野獸"},
"chapter_titles_zh": {"CHAPTER 1": "第一章"},
"style_anchor": {
"register": "literary plain prose",
"avoid": ["四字結構過多", "翻譯腔", "過度書面化"],
"prefer": ["口語節奏", "略諷刺", "短句"]
}
}Step 2.5: Auto-populate nav overrides (MANDATORY — every spine item)
After glossary build, the main session calls
translations_extra.write_nav_overrides(glossary, manifest, book_dir) to
populate <book_dir>/translations_extra.json::nav_overrides from the
glossary's chapter_titles_zh field.
(glossary.write_translations_extra_nav_overrides is a back-compat alias.)
This drives both nav rendering AND bilingual chapter title display in the
assembled EPUB. If translations_extra.json already exists, existing keys
are preserved (user overrides are not clobbered).
Contract — every spine item must have a Chinese nav label.
assemble.py runs in strict_nav=True mode by default and aborts with
ValueError if any spine item's nav label would render English-only after
applying nav_overrides + glossary chapter_titles_zh + the built-in
STRUCTURAL_LABELS_ZH_TW (covers Cover/Title Page/Copyright/
Dedication/Acknowledgments/Notes/Index/About the Author etc.).
This covers three categories explicitly:
- Body chapters — pulled from
chapter_titles_zhautomatically; if the glossary missed one, the main session must add it before assembly. - Image/plate pages (book.opf often lists 10-30 plate inserts whose source
labels are long photo captions) — they have no canonical glossary entry, so
the main session must write a short Chinese label per plate
(e.g.
"圖版:亞瑟·洛克") intonav_overrideskeyed by the source idref. - Front-/back-matter structural pages (Foreword, Preface, Epigraph,
Appendix, Timeline) — fall back to
STRUCTURAL_LABELS_ZH_TWwhen the title matches; otherwise add tonav_overrides.
If the assembler aborts, the error message lists every missing idref + the
fallback English label it saw — fix translations_extra.json and re-run. The
strict_nav=False escape hatch exists only for low-level fixtures inside
the skill's own test suite; never call assembly with it from production
workflows.
Step 4: Translate ch.01 inline (style sample)
Main session translates chapter 1 directly (not via subagent) so the resulting translation becomes the canonical style anchor.
Step 5: Interactive preview gate
Use AskUserQuestion tool to present:
=== Chapter 1 preview ===
[ORIGINAL] <first 300 chars>
[TRANSLATION] <first 300 chars of zh-tw>
=== Glossary ===
<json dump, top 10 entries>Options: [c]onfirm and continue / [g]lossary edit / [s]tyle edit / [r]e-translate ch.1.
On [c]: set state.style_confirmed = true, proceed. On [g]/[s]: accept user input, update glossary.json, retranslate ch.1. On [r]: regenerate ch.01 with current glossary/style.
Bypass condition: if state.style_confirmed == true (resume case), skip the gate.
Step 6: Parallel subagent dispatch (translate items only)
Use the Agent tool with model: "sonnet" for ch.02+ (see "Model selection
discipline" below), batch size = concurrency (default 5). Each task's
prompt is produced by dispatch.build_subagent_prompt(...) and includes:
- Glossary (mandatory translations)
- Style anchor (first 500 chars of ch.01 translation)
- Carryover (last 200 chars of ch.
<N-1>translation) - Source paragraphs wrapped with
[[PARA_1]]..[[PARA_N]]markers - Verification rules requiring the subagent to echo every marker followed by
its translation, starting the response with
[[PARA_1]](no preface)
After each subagent returns, the main session:
- Calls
dispatch.validate_translation(raw, chapter_html)to surface warnings (missing/extra markers, refusal language, preface leak). - On a clean run: calls
dispatch.extract_aligned_translation(raw, N)to get the plain translation text, thenstate.mark_done(state, chapter_id, text). - On misalignment: retry the chapter once with the same prompt; if it still
misaligns, escalate to Opus (see Phase 4) or mark
aup_refusedif the response contains refusal language; markfailedotherwise.
Retry / escalation discipline (post Phase 1-3 upgrades)
After each subagent returns, the main session runs:
warnings = dispatch.validate_translation(raw, chapter_html)- If
warningscontains an entry starting withAUP_REFUSED:→state.mark_aup_refused(state, chapter_id, reason=warnings[0]). Do not retry. - If
warningsis empty →dispatch.extract_aligned_translation(raw, N)→state.mark_done(state, chapter_id, text). - If
warningscontains marker misalignment OR refusal language (other than AUP) OR preface leak → retry once with the same subagent prompt. - If retry still fails → escalate: re-dispatch with
model: "opus"(Phase 4). - If escalation also fails →
state.mark_failed(state, chapter_id, error).
Marker misalignment is the most common warning; preface leak is usually fixed
by strip_known_leak_prefixes before the marker parse, so it rarely surfaces
as a real warning unless the leak text contained no marker at all.
Step 7: Assemble bilingual EPUB
python3 {baseDir}/scripts/assemble.py \
--book "<out_dir>/<book_stem>/" \
--out "<book_stem>_bilingual.epub"assemble.py is a thin orchestrator that sequences four sibling modules:
bilingual_rewriter.insert_bilingualdoes per-paragraph English/中文 interleavingnav_builder.build_nav_xhtml+patch_toc_ncxgenerate the bilingual navarchive_writer.write_from_source_archive(default) orwrite_standalone_archive(fallback) writes the output EPUBopf_builder.build_minimal_opfis used only by the standalone path
Per-page structure: original English text nodes keep their source classes and
also receive src; inserted Traditional Chinese sibling paragraphs receive
tgt tgt-zh plus the inherited source classes. Original relative paths and
internal hrefs are not rewritten.
Auto-bundled translations payload. assemble.py writes two things into
<opf_dir>/translations/ inside the output EPUB so audits can read them:
- Every
*.jsonunder<book_dir>/translations/— user-authored payloads (customsource_only.jsonlists,register_hints.json, etc.) are copied verbatim intoOEBPS/translations/. - Auto-generated
source_only.json— if the user has not authored one, assembly scans every rewrittensource_onlyspine item, collects theclass="src"paragraphs that have no zh sibling, and writes their text intosource_only.json. This satisfies bothtranslation_quality_audit.pyandbilingual_coverage_audit.py(both load the same file from the EPUB to whitelist intentionally-English paragraphs like endnote citations).
Assembly fails closed: any translate item missing its item_NNN_translation.txt
is a hard error. Source-only pages are emitted without translation, and explicit
drops require a reason.
Step 8: Audit gates
All 4 deterministic audits run together via audit_suite:
python3 {baseDir}/scripts/audit_suite.py \
--source "<book_path>" \
--output "<book_stem>_bilingual.epub" \
--book-dir "<out_dir>/<book_stem>"audit_suite.run_all(...) returns list[AuditResult]; the orchestrator can
aggregate via all_passed(results) and report via format_summary(results).
Each AuditResult(name, status, failures, details) is the canonical shape —
the audits previously returned three different shapes, now unified.
Individual audits remain runnable standalone if you want one gate at a time:
python3 {baseDir}/scripts/structural_audit.py \
--source "<book_path>" \
--output "<book_stem>_bilingual.epub" \
--book-dir "<out_dir>/<book_stem>"
python3 {baseDir}/scripts/bilingual_coverage_audit.py \
--source "<book_path>" \
--output "<book_stem>_bilingual.epub"
python3 {baseDir}/scripts/href_resolve_audit.py \
--output "<book_stem>_bilingual.epub"
python3 {baseDir}/scripts/translation_quality_audit.py \
--output "<book_stem>_bilingual.epub"structural_audit.py checks source-vs-output spine representation, missing
translations for translate items, state schema validity, cover page presence,
source-only image preservation, and at least one body chapter.
bilingual_coverage_audit.py and translation_quality_audit.py share OPF
lookup + spine walking through scripts/epub_reader.py (context manager);
bilingual_coverage_audit.py additionally shares the paragraph-walking
algorithm through scripts/content_blocks.py. A missing or malformed
EPUB package is reported as an audit failure rather than raising — this is
the canonical tolerant behavior.
Backward incompatibility (2026-09-09). source_only.json entries now carry an
explicit {src_text, reason} and bare strings are ignored (with one stderr
warning). The old bare-string format encoded the rule "no zh sibling means
exempt", which is what let 506 echoed or misaligned paragraphs through the gate
in earlier books. Consequence: re-running the audits against an EPUB assembled
by an older version reports many failures — those EPUBs carry the old list
format. Assemble and audit run together in the normal pipeline, so this only
bites when auditing a previously shipped file; re-assemble it first.
bilingual_coverage_audit.py fails when a long English content paragraph lacks
an adjacent Han-character sibling, except when the paragraph's text is
listed in OEBPS/translations/source_only.json inside the EPUB (same exception
contract as translation_quality_audit.py). href_resolve_audit.py fails when
any internal XHTML link target is missing from the EPUB zip.
translation_quality_audit.py fails on Round-2-style placeholders,
model-control-token leaks, the synthetic 譯文: prefix, span-concatenated
headings, clearly truncated target paragraphs, Simplified residue, or unlisted
source-only paragraphs. Borderline short targets that look like titles or compact
complete sentences are reported as WARN for human review without blocking the
gate; index-like entries remain FAIL because the corpus shows frequent alignment
errors there. This grading has an inherent ambiguity: a 50–150-character,
single-sentence source truncated to about 21% can still look like a legitimate
compact translation and become WARN (266-paragraph corpus exposure, about 2% of
body prose). It never becomes PASS, so unattended runs must inspect the persisted
state.json.audit_warnings; the driver also returns/logs the warning count.
The bilingual rewriter never prepends Han text merely to satisfy coverage. If a
model returns English/reference text, it is preserved honestly. Assembly emits a
source_only.json exception only with src_text plus a non-empty reason derived
from paragraph location (bibliography/index/notes/publication metadata) or an
explicit manifest source-only strategy. A missing target sibling alone is not an
exception reason. Long unexplained English output therefore fails
bilingual_coverage_audit.py; short identifiers and non-Latin notes may remain
unchanged without being sent through page-role inference.
Step 9: Translation spot-check
Main session samples 5 random paragraphs across chapters:
- Character names match glossary entries
- No obvious omission (translation paragraph count vs. source)
- Tone matches style anchor
Report findings; do not auto-fix.
Step 10: Per-chapter translation log
After each subagent return + validation, the main session calls
translation_log.write_log_entry(...) to persist the full prompt, raw
response, parsed translation, validation warnings, model, and marker counts
under <book_dir>/translation_log/<chapter_id>.json.
When an audit catches a regression in a single chapter, repair it offline without re-dispatching the subagent:
python3 ~/.claude/skills/book-translator/scripts/replay_chapter.py \
--book-dir <out_dir>/<book_stem> \
--chapter item_007 \
--rewrite-translation-fileThen re-run assemble.py on the same book_dir; the rewritten translation
file will be picked up.
State machine (state.json)
{
"book": "animal_farm.epub",
"started": "2026-05-14T03:00:00Z",
"target_lang": "zh-tw",
"glossary_built": true,
"style_confirmed": false,
"chapters": {
"item_001": {"output_strategy": "source_only", "status": "source_ready"},
"item_002": {"output_strategy": "translate", "status": "done", "translation_hash": "abc123", "carryover": "...最後 200 字..."},
"item_003": {"output_strategy": "drop_explicit", "status": "dropped", "reason": "promotional page omitted"}
}
}Allowed output_strategy: translate, source_only, nav_generated,
drop_explicit. Allowed status: pending, in_progress, done, failed,
source_ready, dropped. The unstructured status skipped is invalid.
Resume: re-running on the same book reads state.json → skip done and
source_ready → retry failed once → process pending.
Mutation invariant: output_strategy is the spine item's identity and
is preserved across status mutations. scripts/state.py::ChapterEntry
owns this invariant — the module-level mark_done / mark_failed /
mark_source_ready helpers all delegate to a single dataclass that
guarantees output_strategy is never silently dropped. mark_dropped
is the explicit exception (it replaces output_strategy with
drop_explicit).
Phase 3 — Cross-modal eval gate (deferred to first real translation)
The quality gate evaluates a real Opus-4.7 translation output, not the SKILL.md scaffold. Running it on a synthetic / scaffold-stage sample tests the wrong thing.
When this skill is invoked from within a Claude Code main session (the typical
case), the main-session LLM runs the eval through the Agent tool, NOT the
Python adapter / claude --print subprocess. CC has nesting detection that
blocks recursive claude CLI calls, so the subprocess path will hang.
In-CC flow (use this when the user types /skillify book-translator or
run cross-modal eval from inside a CC session):
- Pick a representative chapter (default fixture: Animal Farm Ch.I →
ch_03). - After translating, save the translated text to
<out_dir>/<book>/chapters/ch_NN_translation.txt. - Main session builds the eval prompt via
scripts.slots.base.build_eval_prompt(skill_text, task_description). - Main session spawns two
Agentcalls in parallel (single message, multiple tool uses):- Slot A:
subagent_type=general-purpose,model=opus, prompt = the eval prompt. - Slot B:
subagent_type=general-purposewith a Bash call invokingpython3 ~/.claude/skills/codex-dispatch/scripts/codex_dispatch_role.py(MODE=verifier, task = the eval prompt) — uses GPT-5 / GPT-4.1 via OpenAI subscription, does not consume CC quota.
- Slot A:
- Parse both JSON replies with
scripts.slots.base.parse_score_json, aggregate withscripts.aggregator.aggregate, persist viascripts.receipt.write_receipt.
From a plain shell (non-CC) flow:
python3 -m scripts.cross_modal_eval \
--task "Translate Chapter 1 of Animal Farm to 台灣繁體中文 with plain literary register" \
--output <out_dir>/animal_farm/chapters/ch_03_translation.txtThat CLI uses ClaudeCodeSlotA.score() which shells out to claude --print —
fine outside CC, hangs inside CC.
Pass criteria (both flows): avg ≥ 8.0 across 5 dimensions, no model scores any
dimension < 5. If fail, iterate SUBAGENT_PROMPT_TEMPLATE in
scripts/dispatch.py.
The deterministic pipeline (full-spine extract → assemble → structural audit) is tested separately from LLM translation quality. Those deterministic tests do not need an LLM.
Translation style discipline
Source: Bocky 學長 2026-05-14 實戰驗證 — Opus 4.7 + 這幾條 vs 不加,品質顯著 提升。已 baked into
SUBAGENT_PROMPT_TEMPLATE(rules 5-8) and the defaultstyle_anchorhints inGLOSSARY_PROMPT.
Layout invariants (handled by assemble.py)
- 每個英文段落後緊接該段中譯,per-paragraph interleave (not chapter-level).
- 詩 / 引言 / 列表 / blockquote / preformatted code / definition lists 全部
比照處理 —
dispatch.html_to_paragraphs/dispatch.html_to_blocks(thin wrappers overscripts/content_blocks.pyextract_paragraphs/extract_blocks) 抓<p>, <h1-h6>, <blockquote>, <li>, <pre>, <dt>, <dd>全納入翻譯,images 透過BLOCK_TAGS維持位置;同一份TEXT_TAGS也是assemble._text_nodes_for_bilingual和bilingual_coverage_audit的單一 source of truth。漏網的內容(極少數)會在 spot-check 抓到。
Translation rules (baked into subagent prompt rules 5-8)
- 專有名詞 / 縮寫 / 技術詞首次出現用英中並列:
- First-in-chapter: 「大型語言模型(LLM)」「人類回饋強化學習(RLHF)」「通用人工智慧(AGI)」
- Subsequent: 中文 only.
- 保留作者第一人稱:
I asked AI...→ 「我問 AI⋯」NOT「筆者問 AI⋯」 — narrative 親近感是商管科普 voice 的核心。 - 例句 / AI 對話 / 打油詩保原作風格與幽默:機智 / 反差 / 自嘲口吻必須留住; AI limerick 可重組押韻(中文押韻為主)不必逐字。
- 整體 register 商管科普 narrative,不學術化:短句 / 口語 / 具體例子 / 白話優於成語堆疊。
Why this is gated up-front
沒這幾條 default Opus 翻商管科普容易:(a) 把 I 翻成「筆者」/「作者」/「我們」失去
narrative;(b) 對話翻成「面試官 vs 應徵者」教科書腔;(c) 縮寫翻成中文後讀者
recall 不回原 term;(d) 整體 register 漂向論文體。Phase 3 cross-modal eval 是
最後守門員。
Output
This skill writes to:
<out_dir>/<book_stem>/glossary.json— extracted glossary (per book)<out_dir>/<book_stem>/state.json— resume state<out_dir>/<book_stem>/spec_terms.json— optional, user-authored: per-book{"terms": {source: 中譯}}table agreed before translation starts. Loaded bydispatch.load_fixed_terms()and appended to the offline system prompt as lookup data (not as another rule). Absent file = previous behaviour. Only the terms a chunk actually contains are injected (dispatch.select_terms_for_text), so the table can be large without bloating every prompt: measured on a 328-term table over 260 chunks, the full table is 6954 chars per chunk while the matching terms average 113 — a 98.4% reduction, and only 2 of 260 chunks match nothing. Broadcasting the whole table instead dilutes attention and the model reads past the instructions it needs. Matching is whole-token and case-sensitive for capitalised terms only, soWeeks(a physician) does not match "weeks" whilegutstill matches a sentence-initial "Gut". Matching normalizes straight/curly apostrophes, hyphen variants, and diacritics on both sides without rewriting the stored source key; an ALL-CAPS source spelling may match a Title Case proper key.
Building a small, decision-focused term list
scripts/build_terms.py does not author an authoritative term table. It
combines mechanical candidates with one or more LLM proposal JSON files and
writes a ranked review queue. Source text is the judge of whether a key exists;
LLM Chinese is always labelled proposed_zh, and only the user may approve it.
Bibliography, index, notes, and publication-metadata pages are excluded from the
existence population. Missing proposals are retained under
dropped_proposals, never silently discarded.
python3 scripts/build_terms.py \
--source source.epub \
--proposals llm-proposals.json \
--out terms-review.jsonProposal JSON may be a top-level list, {"proposals": [...]},
{"terms": [...]}, or a conventional {"terms": {source: zh}} mapping. Rows
accept en, zh, and group, plus optional entity_id, distinguish_from,
user_decided, and east_asian. The last three make the reason for human
review explicit; East Asian names are marked to restore the original Han name
rather than accept phonetic transliteration. OpenCC and the validated
Simplified trigger set are mandatory: if either is unavailable, building fails
instead of silently skipping the zh check.
This whole comparison path is optional (decided 2026-09-09). The pipeline
does not translate a calibration chapter, and build_terms.py runs fine
without any of these flags — it just falls back to weaker ranking signals
(proposal-backed distinction, proper nouns, multi-word terms, low-frequency
words) instead of measured translation impact. Use it only for a book where
the ordering is worth an extra chapter of GPU time.
When aligned with-table and without-table chapter translations already exist, provide all three aligned files explicitly:
python3 scripts/build_terms.py \
--source whole-book.epub --proposals llm-proposals.json \
--comparison-source chapter-source.txt \
--baseline-translation chapter-without-terms.txt \
--termed-translation chapter-with-terms.txt \
--out terms-review.jsonThe three comparison files must contain the same paragraph array in the same
order, serialized as UTF-8 with one blank line between paragraphs. Save
chapter-source.txt from the exact paragraph list sent to the translator,
before chunking; do not reconstruct it later from raw EPUB nodes or chapter
HTML. Those representations can split one logical paragraph into many nodes
(measured 161/140 nodes versus 70 translated paragraphs), and unequal counts
fail closed. The supported way to produce chapter-source.txt is --comparison-chapter,
which reads <book_dir>/chapters/item_NNN.html through the same
dispatch.html_to_paragraphs the translator itself calls, so the array is
aligned by construction rather than by luck:
python3 scripts/build_terms.py \
--source whole-book.epub --proposals llm-proposals.json \
--comparison-chapter "<book_dir>/chapters/item_007.html" \
--baseline-translation chapter-without-terms.txt \
--termed-translation chapter-with-terms.txt \
--out terms-review.json--comparison-source takes a pre-saved array when you already have one.
--comparison-page remains an advanced alternative only when its extracted
node count is already known to align exactly; prefer the other two.
The ranking then uses translation_change_count—how many source occurrences
changed to the proposed wording—not raw source frequency. Every row includes
ranking_reasons. Without that experiment, explicit distinction/user-decision
metadata and word frequency are proxies: Zipf ≥4.3 is excluded as common;
3.3–4.3 is sent to human review only when backed by an LLM/user proposal or
when the mechanical candidate is a proper noun or multiword phrase; pure
mechanical mid-frequency single words remain reference. Zipf <3.3 is retained
as reference. Mechanical n-grams whose first or last token is a stopword are
removed. Proposal-backed rows sort ahead of pure mechanical rows; raw body
frequency is only the final tie-break and is disclosed as
frequency_tiebreak:not_impact_evidence, never presented as impact evidence.
The builder keeps a proposal spelling when it occurs literally; only missing
Title Case/sentence-case and narrow demonym variants are rewritten. Rewrites
choose the most frequent source spelling, preferring lowercase on ties, so a
title encountered first cannot turn a broadly matching lowercase key into a
case-sensitive one. A high
occurrence count alone never makes a term important.
The report also lists person-name token collisions, same-entity Chinese
conflicts, Simplified trigger characters using the sentence-gate trigger set,
and mechanical extractor coverage by people/institutions/concepts. Generated
single-name forms are admitted only when unique within the book's person-name
population; true collisions remain manual. Do not copy proposed_zh into
spec_terms.json without user approval.
<out_dir>/<book_stem>/manifest.json— full OPF spine manifest v2<out_dir>/<book_stem>/chapters/item_NNN.html— extracted source spine items<out_dir>/<book_stem>/chapters/item_NNN_translation.txt— per-item translation fortranslateitems<out_dir>/<book_stem>/translation_log/<chapter_id>.json— per-chapter prompt, raw response, parsed translation, validation warnings, model, and marker counts<out_dir>/<book_stem>/cover.jpg(or.png) — extracted cover image, embedded into the output EPUB byassemble.py(3-strategy lookup: EPUB 3properties="cover-image"→ EPUB 2meta name="cover"→ id-contains-"cover" image)<out_dir>/<book_stem>/images/— every inline image from the source EPUB, flattened to bare filenames.assemble.pycallshtml_to_blocks()to interleave text-translation pairs with standalone image blocks (<div><img/></div>and<figure>wrappers); inline decorative imgs inside<p>text<img/></p>are dropped as visual markers<out_dir>/<book_stem>_bilingual.epub— final bilingual EPUB (the only artifact the user needs to keep)
All paths under user-provided out_dir (default: directory of input epub). The skill does NOT write to ~/.claude, system cache, git, Apple Notes, or any other location.
Fixtures
Two roles, kept distinct:
- Deterministic test fixture (pytest,
test/test_extract_epub.py+test/test_e2e.py):~/ghkb/interested/bilingual_book_maker/test_books/animal_farm.epub— public-domain, ~50K input tokens, 10 body chapters. Stable, free to test against on every commit. - First-real-run target is your choice — any book you legally own. Use the Phase 3 cross-modal eval to validate translation quality on the first chapter before fanning out to the rest of the book. The full pipeline (extract → glossary → style sample → subagent fan-out → assemble → 5 audit gates) is book-agnostic.
Distribution
Disclaimer: this skill is intended for public-domain works or books you
legally own. Do not use it to translate copyrighted material you do not have
the right to reproduce. Per-book overrides (custom dedication / acknowledgments
paragraph translations, custom nav labels) live in
<book_dir>/translations_extra.json and <book_dir>/spec_terms.json — never in this repo.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

