# PDF Translate

> Dich PDF hoc thuat/ky thuat (sach, bai bao co cong thuc toan) sang tieng Viet bang PyMuPDF — giu nguyen cau truc, cong thuc, hinh anh; chi thay phan text. Da kiem chung tren cac chuong sach quantum computing 19 va 71 trang.

- Skill: `manhpp/pdf-translate` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add manhpp/pdf-translate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manhpp/pdf-translate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ManhPP (https://skillmd.com/u/manhpp)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/manhpp/pdf-translate

---


# Quy trinh dich PDF giu nguyen layout

Pipeline 3 buoc: **extract -> dich (model tu viet file trans) -> build -> verify bang render**.
Cac script nam trong `${KIMI_SKILL_DIR}`. Da test voi PyMuPDF 1.27 tren Python 3.12, Windows.

## 0. Moi truong (bat buoc)

- Dung Python co san PyMuPDF 1.27+. Tren may Windows cua user goc:
  `source ~/anaconda3/etc/profile.d/conda.sh && conda activate env-312 && python ...`
  (KHONG goi `python` truc tiep — khong co trong PATH). May khac thi dung env tuong duong.
- Script da co san dong `sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")`
  (console cp1252 se crash neu in tieng Viet). Neu viet script phu, phai co dong nay.
- Font chen: Times New Roman (`times.ttf`, `timesbd.ttf`, `timesi.ttf`, `timesbi.ttf`),
  mac dinh lay tu `C:/Windows/Fonts`; doi bang bien moi truong `PDF_FONT_DIR`.
  Bat ky font serif nao du dau tieng Viet deu dung duoc neu dat dung 4 ten file tren.

## 1. Extract

```bash
python "${KIMI_SKILL_DIR}/extract_pdf.py" <ten>.pdf
```

Sinh ra `<ten>_items.json` (toa do de chen) va `<ten>_dump.txt` (de doc va dich).
Dump co 2 loai item:

- `[pX-Y] (para sz=...)` — doan van ban thuan. Noi dung goc o cac dong tiep theo,
  da danh dau `<b>`, `<i>` theo font goc.
- `[pX-Y-lZ] (mixed sz=...)` — dong lan lon text + toan. Phan nam trong cap `⟨...⟩`
  la TOAN — giu nguyen, khong dich, khong chen.

Block code, block toan thuan, so trang o header (y<45) tu dong bi loai — neu can giu
nguyen mot item nao do (vd listing code bi bat nham), dung SKIP.

## 2. Viet file dich `<ten>_trans.py`

Doc `<ten>_dump.txt`, dich tung id, viet ra `<ten>_trans.py` trong thu muc lam viec:

```python
# -*- coding: utf-8 -*-
TRANS = {
    # para: chuoi HTML (duoc <b>, <i>, <br/>)
    "p0-1": "Doan van da dich, co the <b>in dam</b>, <i>nghieng</i>.",

    # para dang hang bang: list dung bang so dong/o
    "p9-9": ["O 1", "O 2", "O 3"],

    # mixed: list voi SO PHAN TU DUNG BANG so slot text (phan khong nam trong <>)
    # None = giu nguyen ky tu goc (dung cho dau dac biet nhu † trong CMSY)
    "p3-7-l1": ["Khi do", None, "ta co"],
    # Phan tu co the la list [[style, text], ...], style thuoc "r"/"b"/"i"/"bi"
    "p4-2-l0": [["b", "Dinh ly."], ["r", " Gia su ..."]],
}
SKIP = {"p2-4", "p5-1"}          # id giu nguyen (code listing...)
MANUAL = {}                       # xu ly tay, xem muc 5
```

## 3. Build

```bash
python "${KIMI_SKILL_DIR}/build_pdf.py" <ten>.pdf [<ten>-vi.pdf]
```

Build se (1) validate: bao id thieu/thua, mixed sai so slot — phai sach moi chay tiep;
(2) redact text goc (giu anh + line-art nho `PDF_REDACT_IMAGE_NONE` +
`PDF_REDACT_LINE_ART_NONE` — vach phan so la line-art); (3) chen ban dich va in CANH BAO.

## 4. Xu ly canh bao (vong lap chinh)

- `[BOX] id: khong vua rect` — para tran khung. Viet gon lai ban dich.
- `[SCALE] id: scale=0.9x` — insert_htmlbox tu co chu. <= 0.95 thi nen viet gon lai;
  0.95-1.0 co the chap nhan.
- `[OVER] id/sN: can Xpt, co Ypt` — slot mixed tran vao toan/rai le. PHAI sua:
  viet gon lai. Kinh nghiem: tieng Viet trong TNR rong hon uoc luong tay —
  truoc khi chon van phong cho slot chat, DO bang:
  `fitz.Font(fontfile="<PDF_FONT_DIR hoac C:/Windows/Fonts>/times.ttf").text_length(text, size)`.
- `[SHRINK]` — slot phai co font > 0.75pt. Nen viet gon hon.
- Slot thua cho (text lap < ~60% khe ho truoc span toan) -> keo dai cau chu cho
  day, dung de khe ho — nhin se "thua space" nhu loi user tung phan nan.

## 5. MANUAL — khi co che slot thuong khong du

Dung khi can redact/ca chen tay (vd muon thay mot span "not" giua dong toan):

```python
MANUAL = {
  "p18-5-l0": {
    "redact_text_slots": True,        # redact tat ca slot text
    "redact_math_slots": [3],         # redact them math slot index 3 (trong it["slots"])
    "redact_rects": [[x0,y0,x1,y1]],  # redact rect tuy y
    "strip_graphics": [[x0,y0,x1,y1]],# pass rieng: xoa CA line-art cham vao vung
                                     # (vd vach phan so thua, gach chan goc). Para cung dung duoc.
    "inserts": [
      {"x": None,          # x = dau slot text dau, limit = toan ke tiep
       "segs": [["r", "Neu "], ["i", "khong"], ["r", " phai ..."]]},
      {"x": "after_math1", # x = sau math slot index 1, limit = right margin
       "segs": [["r", " thi ..."]]},
      {"x": 97.5, "y": 516.3, "limit": 320.5,  # y/limit tuy chon (y mac dinh = baseline item)
       "segs": [["r", ", voi xac suat 3/4, ..."]]},
    ],
  },
}
```

Luu y quan trong (kinh nghiem chap4, 71 trang):

- Redaction cua PyMuPDF xoa CA KY TU chi can bbox chay rect mot chut → span toan nho
  (|+⟩, tu/mau so phan so chong, dau ^, can, Σ) de bi xoa nham boi rect slot lang gieng.
  build_pdf.py da co co che RESTAMP tu dong: phat hien ky tu toan bi an va dap lai tu
  ban goc bang show_pdf_page (clip theo bbox ky tu, nen trong suot). Canh bao [GHOST]
  = trong vung dap lai co muc span khac → render kiem chung bang mat, thuong vo hai.
- Phan so chong (tu/mau bi extractor tach thanh cac "dong" lech baseline): dung MANUAL
  gom ve 1 baseline, go inline "3/4", redact slot goc + math mau so, strip_graphics
  vach phan so thua.
- Bang co vach ke doc: para dang hang bang (TRANS la list o) — o qua rong se wrap va
  de vach; rut ngan text o theo be rong goc.
- Nhan trong hinh mach (vd C_in/C_out): khong duoc dai hon ban goc, day mach se de chu.
- Sach lon/nhieu trang: chia dump theo cum trang, dich song song bang subagent, merge
  TRANS; check_fit.py (mo phong fit khong can build) giup vong lap nhanh.

## 6. Verify bang mat (bat buoc)

```bash
python "${KIMI_SKILL_DIR}/render_preview.py" <ten>-vi.pdf preview 110        # luoi tong quan
python "${KIMI_SKILL_DIR}/render_preview.py" <ten>-vi.pdf zoom 150 "0,4,8"   # zoom trang nghi ngo
```

Mo PNG (ReadMediaFile) kiem tra: overlap chu/toan, chu de len hinh, space thua,
trang lech le. Cac trang chi xem qua thumbnail 110dpi la chua du cho trang day dac.

## 7. Quy tac dich thuat (da chot voi user)

- KHONG dich word-by-word; dich theo nghia chuyen nganh, van phong sach giao khoa.
- Giu nguyen tieng Anh cho thuat ngu nganh: quantum gate, qubit, Quirk, unitary,
  bra-ket, collapse, Bloch sphere, ten phep bien doi (Pauli, Hadamard, Identity) trong o bang.
- Chuan hoa thuat ngu Viet (sach quantum/toan):
  inner product = tich trong; outer product = tich ngoai;
  orthogonal = truc giao; orthonormal = truc chuan; normalize = chuan hoa;
  basis = co so; identity matrix = ma tran don vi (KHONG "ma tran dong nhat");
  completeness relation = he thuc day du; invertible = kha nghich;
  adjoint/conjugate transpose = chuyen vi lien hop; scalar = vo huong;
  proof = chung minh (cho chat cho phep viet tat "CM").
- Code, ten ham, cu phap: giu nguyen, khong dich.

## 8. Cam bay da gap

- `insert_htmlbox` o PyMuPDF 1.27 tra ve TUPLE (spare, scale), khong phai float.
- Luan redact voi `images=PDF_REDACT_IMAGE_NONE, graphics=PDF_REDACT_LINE_ART_NONE`.
- Rect para phai mo rong xuong toi vat can ke tiep (tinh ca items LAN blocks) —
  thieu buoc nay para se de len doan ben duoi.
- Right margin tinh RIENG tung trang (trang chan/le co the khac nhau, vd 369 vs 394).
- Slot giua hai span toan: can GIUA khe ho; slot canh le phai: limit = right margin.
- Dau † va ky hieu CMSY hep: de `None` o slot tuong ung, giu ky tu goc.