localize-infographic-pdf

# AGENTS.md — using this repo from OpenAI Codex (or any non-Claude agent)

This repo is packaged as a Claude Code *skill* ([SKILL.md](SKILL.md)), but its engine is plain
Python and works in any agent. This file is the Codex-oriented entry point.

## When to use

Use this when asked to **localize / translate / 本地化 / 汉化 a design-exported PDF**
(infographic, one-pager, flyer, poster — often landscape/multi-panel) while keeping the artwork
identical. It erases the source vector/Type3 text and redraws the translation in place.
Do NOT use it for plain document translation or editable Word/PPT files.

## Workflow (run the scripts in order)

Same pipeline as SKILL.md. Pick a work dir (e.g. `work`). All scripts: `SOURCE.pdf [OUTDIR] [PAGE]`.

```bash
S=./scripts                                   # path to this repo's scripts
python3 $S/01_analyze.py  poster.pdf work     # detect text type; list image-baked text; render
python3 $S/02_extract.py  poster.pdf work     # -> work/units.json + work/translator_source.txt + half_*.png
#  TRANSLATE step (see below) -> writes work/translation.json
#  (optional) write work/overrides.json for chart/pill/centered tuning  (references/overrides.md)
python3 $S/03_compose.py  poster.pdf work     # the engine -> work/final_zh.png
python3 $S/04_pdf.py      poster.pdf work out.pdf   # -> out.pdf + work/zh_L.png / zh_R.png for review
#  REVIEW step (visual, see below); fix overrides.json / translation.json; re-run 03 + 04 until clean
#  DOUBLE-VERIFY step (required): independent engine (e.g. `codex exec -s read-only`) proofreads
#     out.pdf's extracted text; fold real findings back, regenerate, re-run once to confirm
#  RETRO (every run): append gaps to references/lessons.md, fold fixes into the skill, git commit + push
```

Deps: `pip install pymupdf numpy opencv-python pillow`. A CJK font is needed for Chinese output
(default macOS `Hiragino Sans GB`; set another via `overrides.json` `"font"`).

**Mode first:** if the source is already bilingual (each item carries both languages) or is basically
a text document with little artwork, overlay *duplicates* content — use **clean-rebuild mode** instead
(extract → drop redundant/source lines → rebuild a clean target-only PDF). See SKILL.md "Direction &
mode" and [references/lessons.md](references/lessons.md).

## The two AI steps (translate / review)

The Claude skill dispatches these as sub-agents. In Codex, run them **as a Codex sub-agent task**
if available, otherwise **inline** (do them yourself in the same session):

- **Translate** — read `work/translator_source.txt` + `work/half_0.png`/`half_1.png`, then write
  `work/translation.json` = `{"<id>":"译文", ...}` covering every id (echo `[KEEP-AS-IS]` ids
  unchanged). Full instructions: [references/agent-prompts.md](references/agent-prompts.md).
- **Review (visual)** — compare `work/zh_L.png`/`work/zh_R.png` against `work/half_0.png`/`half_1.png`;
  report residual source text, mis-sized blocks, smudges/patches, broken controls. Same file.
- **Double-verify (linguistic, independent)** — a *second* engine proofreads the target-language text
  of `out.pdf` (grammar / terminology / consistency / mistranslation) as a cross-check. Prompt in
  [references/agent-prompts.md](references/agent-prompts.md); apply real findings with judgement.

## Claude → Codex tool mapping

| In SKILL.md / references | Codex equivalent |
|---|---|
| `Bash` (run a script) | shell tool / `python3 …` |
| `Read` a file or image | open/read the file (Codex reads PNGs for visual QA too) |
| `Write` a file | create/edit the file (`apply_patch` or write) |
| `Agent` (dispatch translator/reviewer) | Codex sub-agent task, or run that prompt inline yourself |

Everything else (the scripts, `overrides.json` schema, the defect→fix catalogue in
[references/pipeline.md](references/pipeline.md)) is platform-agnostic — read those directly.