Resolve fuzzy entries in dataclasses/faq-library and improve translation skills

.claude/skills/check-terminology/SKILL.md

@@ -13,6 +13,8 @@ Check terminology against project glossary and zh_CN/zh_TW mappings.
 1. **Primary:** `glossary.po` - Official Python glossary translations
 2. **Secondary:** `focused_terminology_dictionary.csv` - 118 key terms
 3. **Tertiary:** `.scripts/google_translate/utils.py` - zh_CN to zh_TW mappings
+4. **Usage evidence (not authority):** `.scripts/translation_memory.sh query "<term>"` - how existing translated .po entries render the term (skip if the command fails)
+5. **Reviewer-enforced terms:** the "Terminology enforced by reviewers" table in `../translate-po/references/review-corrections.md` - pairs reviewers repeatedly corrected (e.g. 傳回→回傳, 您→你, 協議→協定, 運行→執行), some context-dependent (串列 vs 清單, 檔案 vs 文件)
 
 ## Check Process
 
@@ -21,12 +23,14 @@ Check terminology against project glossary and zh_CN/zh_TW mappings.
 2. Check if it's in `references/keep-in-english.md`
 3. If found, use the standard translation
 4. If not found, check `glossary.po` in project root
+5. Run `.scripts/translation_memory.sh query "<term>" --top-k 10` to see existing renderings with `path:line`; if the glossary is silent, report the dominant rendering as a suggestion
 
 ### For a PO File
 1. Extract all translated terms from msgstr
 2. Cross-reference against glossary
 3. Identify forbidden zh_CN terms
-4. Report inconsistencies
+4. For each term that looks inconsistent, run `.scripts/translation_memory.sh query "<English term>" --top-k 10` and compare renderings across files
+5. Report inconsistencies, citing `path:line` from the lookup
 
 ## Error Categories
 
@@ -41,6 +45,10 @@ Example violations:
 ### Category 2: Inconsistent Terms (Should Review)
 Same English term translated differently across files.
 
+Gather evidence with the translation memory lookup and cite each rendering with
+`path:line`. The glossary decides; majority usage only informs a suggestion
+when the glossary is silent.
+
 ### Category 3: Missing from Glossary (Informational)
 New terms not yet in the glossary.
 
@@ -71,6 +79,7 @@ Decision Log:
 
 1. Check `../translate-po/references/terminology.md` first (authoritative, 186 terms)
 2. If term should stay in English, see `references/keep-in-english.md`
+3. To see how a term is actually rendered across files: `.scripts/translation_memory.sh query "<term>"`
 
 ## References
 

.claude/skills/review-rendered-html/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: review-rendered-html
+description: Builds translated PO files into HTML and reviews the rendered page for reading flow and formatting, by reading the extracted page text and checking Playwright screenshots. Use after translating or editing a PO file, before opening a PR.
+argument-hint: <po-file> [<po-file> ...]
+---
+
+# review-rendered-html
+
+PO-level checks (`msgfmt`, `make lint`, terminology) cannot show how a
+translation reads on the published page. reST roles disappear, links and
+literals change spacing, and Sphinx adds its own labels. Review the rendered
+HTML of every page you changed before opening a PR.
+
+## Prerequisites
+
+- CPython clone at `../cpython` on the branch matching `VERSION` in the
+  Makefile, and the docs venv (`make prepare_deps` sets up both)
+- Playwright MCP tools (`browser_navigate`, `browser_take_screenshot`) for
+  screenshots; without them, read the text dump only and say so in the report
+
+## Step 1: Build and dump the rendered text
+
+```bash
+python3 .scripts/render_review.py library/dataclasses.po [faq/library.po ...]
+```
+
+- Builds only the given pages (same Sphinx options as `make build`) and writes
+  the page prose, without code blocks, to `.render-review/<page>.txt`
+- Prints heuristic findings with the line in the text dump; `--no-build`
+  re-checks without rebuilding
+- "build reported problems" about `redirects to builtins/...` comes from a
+  reused build directory and does not affect the page
+
+## Step 2: Read the text dump as a reader
+
+Read `.render-review/<page>.txt` end to end, focusing on paragraphs from the
+entries you changed. For each one check:
+
+- **Flow:** the sentence reads as natural Taiwanese technical writing; no
+  translationese (被…所…, 將會是, 除…之外的其他事項), no dangling clauses
+  after a role's text disappears
+- **Spacing:** one space between CJK and Latin/digits/literals; no space
+  next to full-width punctuation; no stray space inside Chinese text
+- **Punctuation:** full-width `，。：；（）「」` around Chinese; the colon before
+  a code block stays `：`
+- **Completeness:** compare with the English page when meaning is unclear
+
+Confirm or dismiss every heuristic finding by reading its context. Findings in
+entries you did not touch are follow-ups, not part of the current change.
+
+Paragraphs still in English are usually not your bug. Either the entry is
+untranslated, or the PO msgid is older than the CPython clone, because the
+source changed after the last sync. Mention them in the report and don't fix
+them in the PO by hand.
+
+## Step 3: Screenshot and inspect the layout
+
+Serve the build and open the sections you changed:
+
+```bash
+python3 -m http.server 8765 --bind 127.0.0.1 --directory ../cpython/Doc/build/html
+```
+
+Then use the Playwright MCP tools:
+
+1. `browser_resize` to 1280x1600
+2. `browser_navigate` to `http://127.0.0.1:8765/<page>.html?v=<n>#<anchor>`;
+   bump `v` after each rebuild, or the browser shows the cached old page
+3. `browser_take_screenshot` with `filename: ".playwright-mcp/<name>.png"`
+   (the MCP only writes inside the repo; `.playwright-mcp/` is gitignored)
+4. Read the PNG and check: links and `:term:` text sit flush with the Chinese
+   around them, inline code has normal spacing, parameter lists, notes and
+   admonitions keep their structure, and headings and the sidebar TOC show
+   the translated titles
+
+Stop the server when done.
+
+## Common rendered-only problems and fixes
+
+| Rendered | Cause in msgstr | Fix |
+|---|---|---|
+| `field可以` | ``` ``field``\ 可以 ``` | ``` ``field`` 可以 ``` (keep the space after a literal before CJK) |
+| `全域直譯器鎖(GIL) 來` | `` :term:`…`\ (GIL) 來 `` | `` :term:`…`\ （GIL）來 `` (full-width parens, no extra space) |
+| `磁碟區上的 替代資料串流` | `` 的 `替代資料串流 <url>`_ `` | `` 的\ `替代資料串流 <url>`_ `` |
+| `:meth:` or backticks visible | role typo such as `:meth: ` with a space | restore the exact role syntax |
+| `` `\ `` visible | escaped backslash doubled in the PO | one `\\ ` in the PO file (`\ ` in the value) |
+
+A reST role or link must be followed by whitespace or ASCII/closing
+punctuation, so a full-width opening bracket after a role still needs `\ `.
+
+## Report
+
+List per page: findings fixed, findings dismissed (with reason), follow-ups
+in untouched entries, English paragraphs and their likely cause, and the
+screenshots you checked.

.claude/skills/translate-po/SKILL.md

@@ -15,6 +15,27 @@ Translate English PO msgid entries to Traditional Chinese msgstr following all p
 3. Look up terminology in `references/terminology.md`
 4. Check `references/forbidden-terms.md` for zh_CN terms to avoid
 
+## Translation Memory Lookup
+
+Before translating an entry that contains prose, look up how similar text was
+already translated in this repo:
+
+```bash
+.scripts/translation_memory.sh query "<msgid text or its key English terms>"
+```
+
+- Prints up to 5 translated, non-fuzzy entries as `path:line` followed by
+  `msgid:` / `msgstr:` lines (use `--top-k N` for more).
+- To see how one term is rendered elsewhere, query the term alone
+  (e.g. `"context manager"`) or a candidate Chinese rendering of 2+ characters
+  (e.g. `"情境管理器"`).
+- Treat hits as reference for phrasing and term choice, not as authority:
+  `references/terminology.md`, `glossary.po`, and the rules below win when they
+  disagree, and existing translations may contain mistakes.
+- Skip the lookup for code-only entries and very short entries.
+- If the command fails or prints nothing (for example, the engine is not
+  installed), continue without it and do not report the failure.
+
 ## Translation Process
 
 ### Step 1: Content Analysis
@@ -50,8 +71,45 @@ See `references/rst-cheatsheet.md` for complete rules.
 
 1. Check term in `references/terminology.md`
 2. If not found, check `glossary.po` in project root
-3. If uncertain, add `#, fuzzy` flag
-4. Never use zh_CN terms from `references/forbidden-terms.md`
+3. If still not found, run `.scripts/translation_memory.sh query "<term>"` and
+   follow the dominant existing rendering
+4. If uncertain, add `#, fuzzy` flag
+5. Never use zh_CN terms from `references/forbidden-terms.md`
+
+### Step 5: Check Against Past Review Corrections
+
+Reviewers of this repo keep asking for the same fixes. Before finishing,
+re-read every changed msgstr against `references/review-corrections.md`
+(mined from ~1,500 review comments). The most frequent ones:
+
+1. **Phrasing and meaning:** no English word order, piles of 的 or needless
+   被; the meaning must match the source exactly (most common correction)
+2. **Terms reviewers enforce:** argument→引數 / parameter→參數, 回傳 (not
+   傳回/返回), 你 (not 您), 引發 (raise), 設定例外 (C API "set an
+   exception"), 透過, 協定, 命令列, 用戶端, 執行 (not 運行), 產生 (not 生成),
+   串列 only for a Python list (otherwise 清單); see the table in the reference
+3. **Spacing:** no space next to full-width punctuation, after 。, or
+   between CJK characters
+4. **`\\ `:** use it between CJK and markup, but not next to `，。、：；）「」`
+   (a full-width `（` right after markup still needs it)
+5. **Punctuation:** `、` for enumerations; keep `...` as in the source; keep
+   ASCII quotes around literal values
+6. **Markup:** re-add ``literal`` markup Poedit drops; balanced backticks
+7. **Completeness:** no omissions (qualifiers, parentheticals, second
+   occurrences) and no additions the source does not state (超譯)
+8. **Keep English:** socket, token, runtime, yield, library names, and words
+   that are really parameter names; translate comments in code samples
+9. **Consistency:** one rendering per term within a page; search existing
+   translations (translation memory) before coining a term
+10. **PO mechanics:** never just strip `#, fuzzy` without updating the
+    translation; index-only entries as `English（譯文）`
+
+### Step 6: Review the Rendered Page
+
+After the PO file is saved, build and read the rendered page with the
+`review-rendered-html` skill (`python3 .scripts/render_review.py <file>.po`,
+then Playwright screenshots of the changed sections). Spacing around
+literals, roles and links can only be judged on the rendered page.
 
 ## Output Format
 
@@ -71,6 +129,9 @@ Before outputting, verify:
 - [ ] reST syntax preserved
 - [ ] Terminology matches glossary
 - [ ] No forbidden zh_CN terms
+- [ ] Consistent with translation memory hits, unless they conflict with the glossary
+- [ ] Checked against past review corrections (`references/review-corrections.md`)
+- [ ] Rendered page reads naturally and its layout is correct (`review-rendered-html`)
 
 ## Examples
 
@@ -130,3 +191,6 @@ msgstr "可能需要審核的翻譯"
 - `references/terminology.md` - Key term translations (186 terms)
 - `references/forbidden-terms.md` - zh_CN to zh_TW mappings
 - `references/rst-cheatsheet.md` - reST syntax rules
+- `references/review-corrections.md` - What reviewers most often correct, with examples and enforced terms
+- `.scripts/translation_memory.sh` - Translation memory lookup over this repo's .po files
+- `.scripts/render_review.py` - Build pages and check the rendered text (see `review-rendered-html`)