booktrans

name	booktrans
description	PM/coordinator skill for translating a foreign-language book into Korean for GLG's personal reading and audiobook listening. Discuss the book and division of work with GLG, calibrate with one controllable worker on one chunk, review quality and context cost, close the upstream glossary/meta barrier, then decide the next bounded assignment; scale only after evidence and GLG approval. Uses ~/repos/3rd/translate-book unchanged; preserves voice and source surface forms; finishes the EPUB before ontology or platform work. Triggers: booktrans, 책 번역, 영어책 번역, 번역 EPUB, 오디오북 번역, translate-book, Why Machines Learn.
user_invocable	true

booktrans — 책을 먼저 끝내는 번역 입구

Repo: ~/repos/gh/memex-kb. Implementation: ~/repos/3rd/translate-book at the recorded upstream pin. Current work and evidence: memex-kb issue #6.

This is a PM/coordinator skill, not a translation engine and not a bulk-agent launcher. The agent reading it may be Opus, GPT, or another capable model. That agent owns the conversation with GLG, the work plan, sequential dispatch, review, glossary/meta barriers, and final EPUB acceptance. It delegates conversion, chunking, glossary/meta feedback, resume state, and EPUB build to upstream, and delegates bounded translation assignments to controllable workers under a measured PM loop.

Read order

Before translating:

1. ~/repos/gh/memex-kb/PHILOSOPHY.md, section 두 번째 기둥 — 위대한 저작을 그 숨결로 읽기.
2. This skill.
3. ~/repos/3rd/translate-book/SKILL.md in full, then follow its commands.

If these disagree, this skill decides GLG's quality and scope policy; upstream remains the runtime procedure. Do not patch upstream merely to make the prose agree.

PM contract — discuss before dispatch

Before opening a translator, talk with GLG and establish:

• which book/source bytes and target language are in scope;
• what already exists and what is real translation versus passthrough output;
• how upstream chunks map to chapters and today's practical stopping point;
• the quality policy, terminology exceptions, and listening target;
• which exact chunk goes to the first fresh translation worker and on which controllable rail.

Present the plan and current facts before execution. Do not turn “translate this book” into one giant translator assignment, and do not infer that existing output_chunk*.md files are translated without checking their language/content. The PM remains the routing point throughout the book.

Book charter — canonical before throughput

Before advancing past a provisional calibration, the PM and GLG set the book's core direction explicitly. A readable EPUB is not enough when its title, vocabulary, metadata, or final home was never decided; later workers then make locally plausible choices that bend the whole book.

Create a private, book-local CANONICAL.md in the intended delivery directory before a sequential run begins. It is the reproducible book charter, not another translation body or a replacement for upstream state. It must name:

• the canonical source EPUB/PDF beside the final delivery, with SHA-256; any Downloads copy used for conversion must be verified byte-identical or rejected;
• the eventual canonical delivery filename and EPUB metadata (title, author, language), and the ignored upstream temp directory that owns chunks/output/meta/run-state while translating;
• any reference translation as comparison-only, never an input to blend into the result;
• the confirmed Korean title and the first-display/source-anchor convention;
• scope decisions (front matter, notes, bibliography, index) and the actual listening target;
• the small set of core terms/translation stances GLG has approved before scale.

glossary.json v2 remains the execution SSOT for individual source→target mappings. CANONICAL.md records only the compact, human-reviewed core decisions and points to that glossary; do not make a second competing term table. After GLG approves a core term, encode it in v2 glossary, run glossary.py count-frequencies, and let the selective retranslation plan expose affected chunks.

A new book may use one calibration chunk to reveal decisions that were not visible initially, but do not push sequential throughput until the charter's open core questions are reviewed with GLG. Record the exact provisional output that exposed each question; it is evidence, not a mandate to adopt the worker's wording.

Goal and stop rule

The immediate goal is a Korean EPUB that GLG can put on his phone and understand by listening. It does not need to be a literary 99-point translation.

Ask before expanding the work:

Is this required to finish and listen to the book, or can another owner receive it afterward?

If it is about dictcli tuples, andenken ontology, a general vocabulary platform, a new private repository, or a universal document model, record/hand off the question and return to the book. Do not let the long direction prevent today's readable EPUB.

Hard boundaries

• Use ~/repos/3rd/translate-book unmodified. Do not fork it for this work.
• Do not copy/vendor its scripts into memex-kb.
• Do not rebuild capture, inventory, run-state, merge-meta, or orchestration. The discarded a2edcbc experiment reached 10,312 added lines and proved that boundary wrong.
• Keep source books and translated bodies out of this PUBLIC repository.
• Never run git clean -xdf in upstream while ignored artifacts are the only copy.
• Keep source chunks beside translated chunks so the original is always reachable.

Translation policy

Use upstream's glossary.json v2 and meta workflow as the translation-time interface. Do not invent a second glossary system before the book is complete.

GLG source-anchor display

GLG reads Korean technical and philosophical terms more confidently when their source form is visible once. Within each assigned translation turn/chunk, render a glossary-backed term at its first meaningful occurrence as 한국어(source form); render later occurrences in that same chunk as Korean only. Preserve the source spelling/case/abbreviation inside the parentheses. Apply this to meaning-bearing terms, not routine prose; person-name romanization remains a separate judgment.

The glossary's target remains Korean only. The parenthetical is an output-display policy carried in every worker prompt, not a second target or an alias. This keeps the EPUB readable while the source chunks alongside it remain the full return path.

Preserve source surface form

A glossary must not silently expand the form chosen by the author.

Frank Rosenblatt       → 프랭크 로젠블랫
Rosenblatt             → 로젠블랫
artificial intelligence → 인공지능
AI                     → AI

When a short form or abbreviation needs a different target, remove that form from the canonical term's aliases and represent it as an independent v2 term. A surface form must occur in only one term, as required by upstream. Run upstream frequency/plan commands after edits; glossary edits may correctly mark earlier chunks for selective retranslation.

Default rule:

Preserve the length, abbreviation, and register of the source form. Do not expand a short form merely because the glossary knows its canonical entity.

A document-level first-mention expansion is optional and must not be invented by a chunk agent.

Preserve the author's voice

Pass this intent through upstream's custom_instructions slot:

저자의 리듬, 비유, 삽입구, 장난기와 필요한 문장 복잡도를 보존한다. 단지 더 명료하고 간결하게
만들기 위해 문체를 평탄화하지 않는다. 원문의 정식명·약식명·약어 선택을 그대로 보존하며,
약식명이나 약어를 정식명으로 임의 확장하지 않는다.

Natural Korean is welcome, but smoothness must not erase the author. Never omit content to make a sentence simpler.

Calibration-first dispatch — learn the unit before scaling it

Do not assume the right allocation before observing this book. Start in calibration mode:

inspect plan and choose exactly one representative chunk
→ open one fresh, controllable translation worker on the GLG-approved model rail
→ give that chunk, the current term table, neighbor context, and this book's policy
→ worker writes one output_chunkNNNN.md and one honest .meta.json
→ worker reports completion and its current context usage, then stops
→ PM compares source/output: structure, meaning, terminology, voice, and boundary continuity
→ if PASS, record the output against the glossary actually used
→ prepare-merge → resolve evidence-backed findings → apply-merge
→ inspect the changed glossary, selective-retranslation plan, output quality, and worker context cost
→ PM and GLG decide the next assignment

During calibration there is one active translation worker and no parallel dispatch. Do not send the next chunk while the current output is unreviewed, unrecorded, or has unmerged meta. A failed chunk is corrected or reassigned before advancing.

Worker lifecycle and model rail

Use the active harness's controllable subagent surface when the translation worker must be stopped, inspected, or retired after a bounded assignment. The model is GLG's choice and rail availability may override a preferred model; a fresh Terra calibration can be valid evidence when Sonnet quota is unavailable. Do not use Entwurf for this worker role when its lifecycle has no close/cleanup switch.

One calibration assignment is one chunk, but that does not mean every worker must be discarded after one chunk forever. After the barrier closes, the PM may give the same worker one more chunk when its observed context is below 300k tokens and the next assignment is expected to remain below 400k (40% of a 1M context). If numeric context use is unavailable, open a fresh worker. Never make a worker carry the whole book or continue merely to avoid opening a replacement.

After enough representative chunks establish real quality, context cost, and review load, GLG and the PM may explicitly leave calibration mode and choose larger bounded assignments or a controlled parallel wave. Parallelism is a later measured decision, not a default prohibition and not a shortcut the PM may take unilaterally. Before enabling it, define non-overlapping chunk ranges, one glossary snapshot per wave, completion/report routing, and the review/merge barrier. Until GLG makes that phase change explicit, remain sequential.

Keep worker prompts narrow. A translator does not need the whole issue history, the entire book, or ontology plans. It needs the exact source/output paths, current generated term table, read-only neighbor excerpt, custom instructions, meta schema, and the requirement to touch no unassigned chunk. Every calibration dispatch must state:

assignment: chunkNNNN only
read: chunkNNNN + supplied term table + supplied neighbor excerpt
write: output_chunkNNNN.md + output_chunkNNNN.meta.json only
policy: preserve meaning, structure, voice, and source surface form
forbidden: unassigned chunks, glossary mutation, run_state/merge/build, repo code/docs, commit/push
report: immediately send paths, checks, uncertainties, and current context usage to the named PM;
        print the same completion report in the visible conversation, then stop and wait

The PM, never the chunk worker, mutates the glossary, records run state, resolves merge decisions, and chooses whether the next assignment goes to the same worker, a fresh worker, or—only after the explicit phase change—a measured wave.

Use upstream state deliberately: when passthrough output_chunk*.md files exist without records, plan with --retranslate-untracked so byte-identical English placeholders are not accepted as completed translations. Keep meta honest: empty arrays are better than invented entities.

Quality calibration verdict — route evidence, not throughput

When GLG wants to judge a translation route before spending it on a more important book, stop after 2–3 varied chunks rather than translating by inertia: one front-matter/title sample, one dense argumentative prose sample, and one sample carrying domain terms, quotation, footnote, equation, or image when the book has them. Inspect both source and output, not only the worker's report.

If GLG supplies an existing machine translation, compare the same source passage for omitted or reordered meaning, terminology, discourse continuity, and reading rhythm. It is a benchmark only: never blend its prose into the canonical output. Mechanical PASS requires line/paragraph order and Markdown assets to survive; reading PASS requires no hallucination, omission, reversed meaning, or term drift. Record minor calques separately from blocking defects.

A clean small sample proves that the worker/PM/upstream loop is viable; it never certifies a whole book. If the purpose was route evaluation, preserve the artifacts and explicitly pause. Do not turn a successful calibration into automatic throughput.

Acceptance — enough to take home

Mechanical gate

• Every source chunk has one non-empty translated output.
• Markdown structure, image paths, equations, blockquotes, links, and paragraph ordering survive.
• Empty text links may be removed; image empty-alt syntax such as ![](...) must survive.
• Glossary/meta/run-state validation passes and no batch feedback is silently left unmerged.
• EPUB is produced and opens on the target phone/player.

Reading gate

Block completion for:

• omitted content, hallucinated content, or reversed meaning;
• a term drift that changes understanding;
• broken cross-chunk reference or discourse;
• formatting damage that prevents reading/listening.

Do not block the book for isolated awkward tense, particles, or prose that is merely less elegant. A source-form expansion is major when it damages discourse (for example, making an already introduced person sound newly introduced); it is minor when it only changes register or rhythm.

The final pass/fail test is a real chapter listened to on the device. epubcheck and mechanical checks are evidence, not the reading verdict.

Vocabulary recovery — handoff, not ontology work

At a chapter or book barrier, preserve a small handoff from the existing upstream artifacts:

• glossary terms actually used or newly accepted;
• aliases/surface-form decisions;
• conflicts and human decisions with source/chunk evidence;
• book identity and upstream pin.

Deliver this material to the dictcli/andenken owners in a machine-readable form they can consume. This lane does not decide their tuple schema, graph ontology, Denote policy, or ingestion implementation. It only ensures that translation decisions do not disappear in an ignored temp directory.

Do not delay an otherwise usable EPUB to design this downstream system. If no durable private destination has been chosen yet, report the exact artifact paths and preserve them in place.

Reporting

Report progress in book terms, not framework terms:

translated / total chunks
failed or retried chunks
unresolved consequential decisions
EPUB path and size
phone/listening check status
small vocabulary handoff status

Success means: the book is translated well enough to read or hear, and its vocabulary decisions can be handed onward.