--- name: comic-translation description: Translate and re-letter comic pages in Adobe InDesign via Sidekick — white covers traced just inside each balloon outline, translated text lettered on a per-language layer, one type size per language, optically centred. Use whenever the user wants a comic, manga, BD or graphic-novel page translated into another language inside InDesign, wants speech balloons or captions covered and re-lettered, wants a translation layer per language, or mentions lettering, balloons, "cover the English", scanlation-style typesetting or a page "like the last one" in a comic localisation project — even if they don't say "skill" or name the method. metadata: version: "1.1.0" --- # Comic translation and lettering in InDesign This skill turns a placed comic page into per-language lettering layers: for every balloon, a white cover that hides the source text without touching the artist's outline, and the translation lettered on top the way a professional letterer would — evenly placed, comfortable margin, natural line breaks, one size per language. It runs through the Sidekick for InDesign MCP tools (`execute`, `get_layout`, `snapshot`, `show_snapshot`) plus Python in the workspace. The InDesign code is UXP JavaScript, not ExtendScript; wrap every change in `app.doScript(fn, ScriptLanguage.UXPSCRIPT, [], UndoModes.ENTIRE_SCRIPT, '')` so a failure never leaves half-built artifacts and the user can undo in one step. ## Page scope (every InDesign script) Books are lettered page by page into the same document, so every script works on ONE page: set `PAGE_INDEX` (0-based) and it only creates, changes or deletes items on that page. Rebuilding page 14 never touches page 13. - Lettering is found by label: `sidekick__cover_NN`, `sidekick__balloon_NN` (built by `03_build_layer.js`) and `sidekick__caption_NN` (hand-set captions, kept on rebuild). Temporary helpers use `sidekick_temp_*`. - Layers, paragraph/object styles and swatches are document-wide. Scripts create them when missing but never delete a lettering layer, and never restyle an existing style unless you set `UPDATE_STYLE = true` (that changes every page that uses it). - Coordinates from `trace_covers.py` / `fit_sizes.py` are mm from the page's top-left corner; the scripts add the page's origin, so spread rulers and facing pages work. - Layer visibility is document-wide in InDesign; that is the only thing `06_finalize.js` changes beyond the page. - Before a rebuild on a page next to finished ones, the build report's `otherPages` must say "unchanged" for every other page. ## What the user usually asks for - Which page(s), which target languages, a layer per language. - A font per language (e.g. a comic font in all caps for Latin scripts, PingFang SC for Simplified Chinese) and one type size per language. - Terms to keep untranslated (e.g. a hero's name stays in English in one language). - An end state: which layer visible, Preview mode, page fitted. - Temporary helpers (grids, measuring frames) hidden or removed when done. If any of this is missing and would change the result (target language, font), ask once; otherwise pick sensible defaults and say what you picked. ## Workflow Keep a task list; the stages below are the list. ### 1. Inspect the document - `get_layout(includeItems: true)`: page size, units (expect mm), the placed art. - `execute`: layers (art layer is often locked — that's fine), links, and fonts (`app.fonts` names look like `Family\tStyle`). Find the requested fonts; if a comic font isn't named, look for one (Classic Comic, CC Wild Words, Anime Ace, Komika…). - `snapshot` the page; count balloons, captions and sound effects. Agree what's in scope (page numbers and signatures stay). ### 2. Map the balloons - Run `scripts/indesign/01_temp_grid.js` with `PAGE_INDEX` (5 mm grid with labels on its own layer; labels are mm from the page's top-left). - Take zoomed region snapshots (`region` 0..1 over the page, ~0.25–0.5 page wide). For each balloon note a rough outline bbox `[L, T, R, B]` in mm, which balloons overlap and **which one is drawn on top**, and where a balloon is clipped by a panel frame or breaks out of it (the art then has no frame line beside it). - Hide the grid layer as soon as you have the numbers. ### 3. Trace the covers (do this before fitting text) Covers must sit just inside each outline. Ovals fitted to estimates chip into hand-drawn outlines — the user noticed this on the first page — so trace the real paper instead: 1. Hide every lettering layer and the grid. Take full-detail region snapshots that contain every balloon whole (the tool says "387 dpi" when it is at maximum detail; keep regions ≤ ~0.55 of the page width to get there). 2. Each snapshot JPEG is saved to the conversation's `tool-results/` folder (`ls -t …/tool-results/*.jpg | head`); the tool output also shows the path. 3. Write a config (schema: `references/trace-config.md`) and run `python3 scripts/trace_covers.py config.json --out covers.json --debug-dir out/`. 4. **Read every `check_*.png`**: the green contour must run inside every black outline, flat only at panel frames, never across a neighbouring balloon. Red pixels mark ink the cover misses — fine if it belongs to a neighbouring balloon, a problem if it's source text. Fix leaks or misses per `references/lessons.md`, then re-run. ### 4. Translate and break lines - Translate for speech, not word for word; keep it about as long as the source. - Break lines by hand into a lozenge (short–long–short) that matches the balloon's shape; a balloon flattened by a panel frame takes wider lines on its flat side. - Rules per script: `references/lettering-rules.md` (Latin, all caps) and `references/chinese-typesetting.md` (Simplified Chinese). ### 5. Measure and fit one size per language 1. `scripts/indesign/02_measure_lines.js` with the font and all balloons' texts (plus alternative breaks as `b4.alt`) → `widths_.json` (mm at 10 pt). It also returns the font's ink `up`/`down`; pass them to the fitter if the font isn't in a profile. 2. `python3 scripts/fit_sizes.py covers.json widths_.json --profile latin-caps` (or `cjk`) lists the maximum size each balloon allows and the limiting ones. 3. Choose one size per language (round down to 0.25 pt). If one balloon drags everyone down, re-break or reword it and measure again — that beats shrinking the whole page. A flat top clipped by a panel frame can take a smaller margin to the frame: `--margin-for b4=1.25`. 4. `fit_sizes.py … --size S --pick b4=b4.alt --out centers_.json` gives each balloon's ink centre. "DOES NOT FIT" means re-break, reword or lower S. ### 6. Build the layers `scripts/indesign/03_build_layer.js` once per language, with PAGE_INDEX, COVERS, CENTERS, TEXTS and the style block. It reuses the language layer (creating it above the art only if missing), replaces only this page's covers and balloon frames for that language, and adds a cover and an auto-sized text frame per balloon (one paragraph per line), centred on its ink. Styles are created when missing; an existing style is left alone and any difference from the style block is reported in `styleDiffs`. A hand-set caption on the page (`sidekick__caption_*`) is kept and brought in front of the new covers. Check the report: `otherPages` must say "unchanged". Covers are on each language layer so each layer stands alone. Then `scripts/indesign/04_optical_center.js`: indents each line so its ink, not its advance width, is centred. Essential for CJK lines ending in full-width punctuation. Paste JSON straight into the script's data block; ~12 KB of covers is fine. ### 7. Verify - Snapshot each language at full detail, row by row. Look for: leftover source strokes, nicked or thinned outlines, lines crowding an edge, wrong glyphs (missing-glyph boxes, straight quotes, `...` instead of `…`). - Downscaled whole-page snapshots hide outline damage — judge outlines only at full detail, and compare against the art with lettering hidden when unsure. - `05_update_covers.js` doubles as a checker: it lists every line end closer than 1 mm to its cover edge. After re-tracing covers, run it to swap shapes and re-check. ### 8. Finish `scripts/indesign/06_finalize.js` with PAGE_INDEX: removes this page's grid and other temp items, deletes temp layers and grid swatches only once no page uses them, shows the requested layer only, Preview mode, page fitted. Report briefly: layers, fonts and sizes, anything you changed in wording to make it fit, and anything still tight. ## Reference files - `references/lessons.md` — pitfalls so far: cover chipping and its fix, tracer leaks, UXP quirks, verification traps, and page scoping. Read before step 3. - `references/lettering-rules.md` — Latin-script lettering (caps, punctuation, breaks). - `references/chinese-typesetting.md` — Simplified Chinese: size, leading, punctuation, line-break prohibitions, optical centring, names. - `references/trace-config.md` — trace_covers.py config schema and tuning knobs. ## Scripts | file | runs in | does | |---|---|---| | `scripts/trace_covers.py` | workspace Python | traces covers inside outlines from snapshots | | `scripts/fit_sizes.py` | workspace Python | max size per balloon; ink centres at a chosen size | | `scripts/indesign/01_temp_grid.js` | Sidekick `execute` | temporary 5 mm grid on one page (or remove it) | | `scripts/indesign/02_measure_lines.js` | Sidekick `execute` | line widths at 10 pt + font ink extents | | `scripts/indesign/03_build_layer.js` | Sidekick `execute` | one page, one language: covers, text frames, ink centring | | `scripts/indesign/04_optical_center.js` | Sidekick `execute` | per-line optical centring | | `scripts/indesign/05_update_covers.js` | Sidekick `execute` | swap covers on one page, report tight lines | | `scripts/indesign/06_finalize.js` | Sidekick `execute` | clean up one page's helpers, final view | Python needs `numpy`, `opencv-python` (cv2) and `scipy`; install with `pip install --break-system-packages` if missing.