diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000000..b035b0ca27 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,46 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-settings.json", + "hooks": { + "PreToolUse": [ + { + "matcher": "Edit", + "hooks": [ + { + "type": "command", + "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q '\\.po\"'; then echo '[Translation Context] Remember: Use skills translate-po, terminology-check, validate-translation. Check doc-translate/references/terminology.md for terms.'; fi" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Edit", + "hooks": [ + { + "type": "command", + "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q '\\.po\"'; then echo '[Post-Edit Reminder] Run: make lint to verify reST syntax. Check terminology with terminology-check skill.'; fi" + } + ] + }, + { + "matcher": "Write", + "hooks": [ + { + "type": "command", + "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q '\\.po\"'; then echo '[Post-Write Reminder] PO file modified. Verify: 1) Line length <= 79 chars, 2) Terminology consistency, 3) reST syntax with make lint'; fi" + } + ] + } + ] + }, + "permissions": { + "allow": [ + "Bash(make lint)", + "Bash(make build *)", + "Bash(make fuzzy)", + "Bash(make todo)", + "Bash(make progress)", + "Bash(powrap *)" + ] + } +} diff --git a/.claude/skills/check-terminology/SKILL.md b/.claude/skills/check-terminology/SKILL.md new file mode 100644 index 0000000000..d7d46fe9d6 --- /dev/null +++ b/.claude/skills/check-terminology/SKILL.md @@ -0,0 +1,78 @@ +--- +name: check-terminology +description: Checks terminology consistency against project glossary and identifies zh_CN terms that need conversion to zh_TW. Use to verify term usage. +argument-hint: +--- + +# check-terminology + +Check terminology against project glossary and zh_CN/zh_TW mappings. + +## Terminology Sources + +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 + +## Check Process + +### For a Single Term +1. Search in `../translate-po/references/terminology.md` +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 + +### 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 + +## Error Categories + +### Category 1: Forbidden Terms (Must Fix) +zh_CN terms that must be converted to zh_TW. + +Example violations: +- `函數` -> should be `函式` +- `返回` -> should be `回傳` +- `對象` -> should be `物件` + +### Category 2: Inconsistent Terms (Should Review) +Same English term translated differently across files. + +### Category 3: Missing from Glossary (Informational) +New terms not yet in the glossary. + +## Context Decision Log + +When a reviewer decides a translation depends on nearby context (above/below), +record the decision here for future reference. Keep entries short and specific. + +Format: +- **Term/pattern:** ... +- **Decision:** ... +- **Context cue:** ... +- **Example:** `source` -> `translation` + +Example: +- **Term/pattern:** 類型 / 型別 +- **Decision:** 用語依上下文；Python 型別物件用「型別」，一般分類用「類型」 +- **Context cue:** 出現 `int/str/dict/type` 或 "type object" +- **Example:** "two types of packages" -> "兩種類型的套件" + +Decision Log: +- **Term/pattern:** 類型 / 型別 +- **Decision:** 用語依上下文；Python 型別物件用「型別」，一般分類用「類型」 +- **Context cue:** 出現 `int/str/dict/type` 或 "type object" +- **Example:** "two types of packages" -> "兩種類型的套件" + +## Quick Lookup + +1. Check `../translate-po/references/terminology.md` first (authoritative, 186 terms) +2. If term should stay in English, see `references/keep-in-english.md` + +## References + +- `../translate-po/references/terminology.md` - Complete term translations (186 terms) +- `references/keep-in-english.md` - Terms that stay in English diff --git a/.claude/skills/check-terminology/references/keep-in-english.md b/.claude/skills/check-terminology/references/keep-in-english.md new file mode 100644 index 0000000000..8f15fc7e41 --- /dev/null +++ b/.claude/skills/check-terminology/references/keep-in-english.md @@ -0,0 +1,73 @@ +# Terms to Keep in English + +These terms should NOT be translated. They remain in English in all translations. + +## Python Keywords + +All Python keywords stay in English: +``` +def, class, if, else, elif, for, while, try, except, finally, +with, as, pass, break, continue, raise, assert, yield, from, +global, nonlocal, del, in, is, not, and, or, return, import, +async, await, lambda, True, False, None +``` + +## Built-in Type Names (in code context) + +When referring to actual Python types in code: +``` +int, float, str, bytes, bool, complex +list, tuple, dict, set, frozenset +iterator, generator, iterable +range, slice, type, object +``` + +Note: In prose, these may be translated (e.g., "a list" -> "一個串列") + +## Standard Library Modules + +Module names stay in English: +``` +os, sys, re, json, pickle, collections, itertools, functools, +datetime, logging, unittest, typing, asyncio, pathlib, etc. +``` + +## Exception Class Names + +All exception names stay in English: +``` +Exception, ValueError, TypeError, AttributeError, KeyError, +IndexError, ImportError, RuntimeError, NameError, StopIteration, +FileNotFoundError, PermissionError, ConnectionError, TimeoutError, +NotImplementedError, MemoryError, RecursionError, ZeroDivisionError, +OverflowError, UnboundLocalError, AssertionError, SyntaxError, +IndentationError, TabError, UnicodeError, UnicodeDecodeError, +UnicodeEncodeError, UnicodeTranslateError +``` + +## Special Method Names + +All dunder methods stay in English: +``` +__init__, __str__, __repr__, __len__, __getitem__, __setitem__, +__delitem__, __contains__, __iter__, __next__, __enter__, __exit__, +__call__, __new__, __del__, __eq__, __hash__, __bool__, etc. +``` + +## Technical Terms (Context Dependent) + +These may stay in English in technical contexts: +- `runtime` (執行時期 in prose) +- `mock`, `patch` (testing terms) +- `pickle` (serialization) +- `GIL` (Global Interpreter Lock) +- `API` (Application Programming Interface) +- `URL`, `HTTP`, `HTML`, `JSON`, `XML` +- `CPU`, `RAM`, `I/O` + +## Brand/Project Names + +- Python, CPython, PyPy, Jython +- Sphinx, reStructuredText (reST) +- GitHub, GitLab +- NumPy, pandas, Django, Flask diff --git a/.claude/skills/translate-po/SKILL.md b/.claude/skills/translate-po/SKILL.md new file mode 100644 index 0000000000..0c8b21e000 --- /dev/null +++ b/.claude/skills/translate-po/SKILL.md @@ -0,0 +1,132 @@ +--- +name: translate-po +description: Translates PO file entries from English to Traditional Chinese (zh_TW) following project conventions. Use when translating new PO files or untranslated entries. +argument-hint: +--- + +# translate-po + +Translate English PO msgid entries to Traditional Chinese msgstr following all project rules. + +## Prerequisites + +1. Read the full msgid before translating +2. Check msgctxt and translator comments for context +3. Look up terminology in `references/terminology.md` +4. Check `references/forbidden-terms.md` for zh_CN terms to avoid + +## Translation Process + +### Step 1: Content Analysis +Identify content type: +- **Pure prose:** Translate normally +- **Code-only:** Preserve exactly (no translation) +- **Mixed:** Translate prose, preserve code/roles +- **reST structural:** Preserve directives, translate display text + +### Step 2: Apply Rules + +**Punctuation:** +- Chinese text: Full-width `「」（）、，。：；！？` +- English text: Half-width `(),.;:!?` + +**CJK-Latin Spacing:** +- Add space between Chinese and Latin: "使用 CPU 運算" (correct) +- No space with symbols: "使用「CPU」運算" (correct) + +**Line Width:** Max 79 characters (use multi-line format for longer text) + +### Step 3: reST Handling + +See `references/rst-cheatsheet.md` for complete rules. + +**Key patterns:** +- `:mod:`os`` -> Keep unchanged +- `:term:`iterator`` -> `:term:`疊代器 `` +- Chinese before role: "參閱\\ :mod:`os`" +- After `::` markers: "範例： ::" + +### Step 4: Terminology Workflow + +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` + +## Output Format + +``` +msgid "Original English text" +msgstr "翻譯後的中文內容" +``` + +For uncertain translations, add `#, fuzzy` flag before the entry. + +## Quality Checklist + +Before outputting, verify: +- [ ] Line length <= 79 characters +- [ ] Full-width punctuation in Chinese text +- [ ] CJK-Latin spacing correct +- [ ] reST syntax preserved +- [ ] Terminology matches glossary +- [ ] No forbidden zh_CN terms + +## Examples + +### Simple Prose +``` +msgid "Python is a programming language." +msgstr "Python 是一種程式語言。" +``` + +### With Terminology +``` +msgid "This function returns an iterator." +msgstr "此函式回傳一個疊代器。" +``` + +### With reST Role +``` +msgid "See :func:`len` for details." +msgstr "詳情請參閱\\ :func:`len`。" +``` + +### With Link +``` +msgid "Visit the `Python website `_." +msgstr "請造訪 `Python 網站 `_。" +``` + +### With Term Reference +``` +msgid "Returns a :term:`context manager`." +msgstr "回傳一個\\ :term:`情境管理器 `。" +``` + +### Mixed Content +``` +msgid "The :class:`list` type is a :term:`mutable` sequence." +msgstr ":class:`list` 型別是一個\\ :term:`可變物件 ` 序列。" +``` + +### Multi-line Format +``` +msgstr "" +"第一行翻譯內容" +"第二行繼續翻譯。" +``` + +### Fuzzy Flag +Add `#, fuzzy` when translation is uncertain or needs human review: +``` +#, fuzzy +msgid "Original text" +msgstr "可能需要審核的翻譯" +``` + +## References + +- `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 diff --git a/.claude/skills/translate-po/references/forbidden-terms.md b/.claude/skills/translate-po/references/forbidden-terms.md new file mode 100644 index 0000000000..6384bae82a --- /dev/null +++ b/.claude/skills/translate-po/references/forbidden-terms.md @@ -0,0 +1,64 @@ +# Forbidden zh_CN Terms + +These Simplified Chinese (zh_CN) terms MUST be converted to Traditional Chinese (zh_TW). + +## Critical Conversions + +| Forbidden (zh_CN) | Required (zh_TW) | English | +|-------------------|------------------|---------| +| 創建 | 建立 | create | +| 代碼 | 程式碼 | code | +| 信息 | 資訊 | information | +| 模塊 | 模組 | module | +| 標誌 | 旗標 | flag | +| 異常 | 例外 | exception | +| 解釋器 | 直譯器 | interpreter | +| 對象 | 物件 | object | +| 支持 | 支援 | support | +| 默認 | 預設 | default | +| 字符串 | 字串 | string | +| 緩存 | 快取 | cache | +| 調用 | 呼叫 | call | +| 哈希 | 雜湊 | hash | +| 類型 | 型別 | type | +| 子類 | 子類別 | subclass | +| 實現 | 實作 | implement | +| 數據 | 資料 | data | +| 返回 | 回傳 | return | +| 指針 | 指標 | pointer | +| 字段 | 欄位 | field | +| 擴展 | 擴充 | extension | +| 遞歸 | 遞迴 | recursive | +| 用戶 | 使用者 | user | +| 算法 | 演算法 | algorithm | +| 優化 | 最佳化 | optimize | +| 字符 | 字元 | character | +| 設置 | 設定 | setting/configure | +| 線程 | 執行緒 | thread | +| 進程 | 行程 | process | +| 迭代 | 疊代 | iterate | +| 內存 | 記憶體 | memory | +| 打印 | 印出 | print | +| 異步 | 非同步 | async | +| 調試 | 除錯 | debug | +| 堆棧 | 堆疊 | stack | +| 回調 | 回呼 | callback | +| 公共 | 公開 | public | +| 函數 | 函式 | function | +| 變量 | 變數 | variable | +| 常量 | 常數 | constant | +| 添加 | 新增 | add | +| 轉義 | 跳脫 | escape | +| 基類 | 基底類別 | base class | +| 頭文件 | 標頭檔 | header | +| 兼容 | 相容 | compatible | +| 宏 | 巨集 | macro | +| 描述符 | 描述器 | descriptor | +| 字節 | 位元組 | bytes | + +## Usage + +When reviewing or writing translations: +1. Search for any forbidden terms in your translation +2. Replace with the required zh_TW equivalent +3. Verify context is appropriate for the replacement diff --git a/.claude/skills/translate-po/references/rst-cheatsheet.md b/.claude/skills/translate-po/references/rst-cheatsheet.md new file mode 100644 index 0000000000..d651eb08ba --- /dev/null +++ b/.claude/skills/translate-po/references/rst-cheatsheet.md @@ -0,0 +1,111 @@ +# reST Syntax Cheatsheet + +Rules for preserving reStructuredText syntax in translations. + +## Common Roles + +| Role | Purpose | Example | +|------|---------|---------| +| `:mod:` | Module reference | `:mod:`os`` | +| `:func:` | Function reference | `:func:`len`` | +| `:class:` | Class reference | `:class:`list`` | +| `:meth:` | Method reference | `:meth:`str.split`` | +| `:attr:` | Attribute reference | `:attr:`__name__`` | +| `:data:` | Data reference | `:data:`sys.path`` | +| `:const:` | Constant reference | `:const:`True`` | +| `:term:` | Glossary term | `:term:`iterator`` | +| `:ref:` | Cross-reference | `:ref:`section-name`` | +| `:pep:` | PEP reference | `:pep:`8`` | +| `:exc:` | Exception reference | `:exc:`ValueError`` | +| `:doc:` | Document reference | `:doc:`tutorial/index`` | + +## Role Translation Rules + +### Keep Unchanged +``` +:mod:`os` -> :mod:`os` +:func:`len` -> :func:`len` +:exc:`ValueError` -> :exc:`ValueError` +``` + +### Translate with Target +``` +:term:`iterator` -> :term:`疊代器 ` +:term:`namespace packages ` -> :term:`命名空間套件 ` +:ref:`detail-section` -> :ref:`詳細說明 ` +:ref:`the remaining cases ` -> :ref:`其餘情況 ` +``` + +## Backslash Escaping + +Use `\\ ` (backslash-backslash-space) as zero-width separator: + +### CJK Before Role +``` +# Wrong +參閱:mod:`os`模組 + +# Correct +參閱\\ :mod:`os` 模組 +``` + +### CJK After Link +``` +# Wrong +`連結 `_中 + +# Correct +`連結 `_\\ 中 +``` + +### Full-width Punctuation After Role +``` +# May break build +:term:`object`（ + +# Correct +:term:`object`\\（ +``` + +## Link Syntax + +``` +# Original +`Python website `_ + +# Translated (keep URL, translate display) +`Python 網站 `_ +``` + +## Code Block Markers + +The `::` marker introduces a code block: + +``` +# Original +Here is the code:: + +# Translated (use fullwidth colon before ::) +程式碼如下： :: +``` + +When source ends with `::`, translate to keep `::` while using a fullwidth colon: +``` +msgid "blah blah::" +msgstr "blah blah： ::" +``` + +## Literal Blocks + +Preserve indentation and content exactly. Only translate comments if needed. + +## Multi-line Format + +For long translations, use PO multi-line format: +``` +msgstr "" +"第一行的翻譯內容 " +"延續到第二行。" +``` + +Each line must be <= 79 characters including quotes. diff --git a/.claude/skills/translate-po/references/terminology.md b/.claude/skills/translate-po/references/terminology.md new file mode 100644 index 0000000000..df7894198d --- /dev/null +++ b/.claude/skills/translate-po/references/terminology.md @@ -0,0 +1,193 @@ +# 術語表摘錄 + +以下內容為術語表/翻譯對照摘錄，翻譯時請優先參考此處與 `glossary.po`。 + +| 原文 | 翻譯 | 說明 | +| --- | --- | --- | +| abstract base class | 抽象基底類別 | | +| access | 存取（勿用「訪問」） | | +| annotate function | 註釋函式 | | +| annotation | 註釋 | | +| approximate | 近似 | | +| argument | 引數 | | +| asynchronous context manager | 非同步情境管理器 | | +| asynchronous generator | 非同步產生器 | | +| asynchronous generator iterator | 非同步產生器疊代器 | | +| asynchronous iterable | 非同步可疊代物件 | | +| asynchronous iterator | 非同步疊代器 | | +| attribute | 屬性 | | +| awaitable | 可等待物件 | | +| binary file | 二進位檔案 | | +| boolean | boolean、布林 | | +| borrowed reference | 借用參照 | | +| bytecode | 位元組碼 | | +| bytes-like object | 類位元組串物件 | | +| call | 呼叫（invoke 可譯為「叫用」、「呼叫」） | | +| callable | 可呼叫物件 | | +| callback | 回呼 | | +| child | 子代、下代 | | +| cipher | 密碼 | | +| circular reference | 循環參照 | | +| class | 類別 | | +| class variable | 類別變數 | | +| closure variable | 閉包變數 | | +| complex number | 複數 | | +| concurrency | 並行性 | | +| condition | 條件 | | +| context | 情境 | | +| context management protocol | 情境管理協定 | | +| context manager | 情境管理器 | | +| context variable | 情境變數 | | +| contiguous | 連續的 | | +| contributor | 貢獻者 | | +| coroutine | 協程 | | +| coroutine function | 協程函式 | | +| current | 目前（勿用「當前」） | | +| decorator | 裝飾器 | | +| deprecated | 已棄用 | | +| descriptor | 描述器 | | +| dictionary | dictionary、字典 | | +| dictionary comprehension | 字典綜合運算 | | +| dictionary view | 字典檢視 | | +| docstring | 說明字串 | | +| document | 文件（勿用「文檔」） | | +| duck-typing | 鴨子型別 | | +| dunder | 雙底線 | | +| element | 元素 | | +| evaluate | 給值 / 計算 | | +| evaluate function | 求值函式 | | +| exception | 例外 | | +| expression | 運算式（但 regular expression 翻成「正規表示式」） | | +| extension module | 擴充模組 | | +| f-string | f 字串 | | +| f-strings | f 字串 | | +| file object | 檔案物件 | | +| file-like object | 類檔案物件 | | +| filesystem encoding and error handler | 檔案系統編碼和錯誤處理函式 | | +| finalizing / finalize | 最終化 | | +| finder | 尋檢器 | | +| flag | 旗標 | | +| float | float、浮點數 | | +| floor division | 向下取整除法 | | +| free threading | 自由執行緒 | | +| free variable | 自由變數 | | +| function | 函式 | | +| function annotation | 函式註釋 | | +| garbage collection | 垃圾回收 | | +| generator | 產生器 | | +| generator expression | 產生器運算式 | | +| generator iterator | 產生器疊代器 | | +| generic function | 泛型函式 | | +| generic type | 泛型型別 | | +| global | 全域 | | +| global interpreter lock | 全域直譯器鎖 | | +| hash-based pyc | 雜湊架構的 pyc | | +| hashable | 可雜湊的 | | +| helper | 幫助函式、輔助函式 | | +| identity | 識別性 | | +| immortal | 不滅 | | +| immutable | 不可變物件 | | +| import | import（不翻譯）、引入 | | +| import path | 引入路徑 | | +| importer | 引入器 | | +| importing | 引入 | | +| index | 索引 | | +| instance | 實例 | | +| int | int、整數 | | +| interactive | 互動的 | | +| interpreted | 直譯的 | | +| interpreter | 直譯器 | | +| interpreter shutdown | 直譯器關閉 | | +| introduce | 引進 | | +| invoke | 叫用（勿譯為「調用」） | | +| iterable | 可疊代物件 | | +| iterate | 疊代 | | +| iteration | 疊代 | | +| iterator | 疊代器 | | +| key function | 鍵函式 | | +| keyword argument | 關鍵字引數 | | +| level | 階 / 層級 / 層 | | +| lexical analyzer | 詞法分析器 | | +| library | 函式庫 | | +| list | list、串列 | | +| list comprehension | 串列綜合運算 | | +| loader | 載入器 | | +| local | 區域 | | +| locale encoding | 區域編碼 | | +| lock | 鎖 | | +| loop | 迴圈 | | +| magic method | 魔術方法 | | +| mapping | 對映 | | +| meta path finder | 元路徑尋檢器 | | +| metaclass | 元類別 | | +| metadata | 詮釋資料 | | +| method | method、方法 | | +| method resolution order | 方法解析順序 | | +| mock | mock | | +| module | module、模組 | | +| module spec | 模組規格 | | +| mutable | 可變物件 | | +| named tuple | 附名元組 | | +| namespace | 命名空間 | | +| namespace package | 命名空間套件 | | +| nested scope | 巢狀作用域 | | +| new-style class | 新式類別 | | +| object | 物件 | | +| operand | 運算元 | | +| operator | 運算子 | | +| optimized scope | 最佳化作用域 | | +| optional module | 可選模組 | | +| package | 套件 | | +| parameter | 參數 | | +| parent | 父- / 上代 | | +| parse | 剖析 | | +| parser | 剖析器 | | +| patch | patch | | +| path based finder | 基於路徑的尋檢器 | | +| path entry | 路徑項目 | | +| path entry finder | 路徑項目尋檢器 | | +| path entry hook | 路徑項目鉤 | | +| path-like object | 類路徑物件 | | +| policy | 政策 / 原則 | | +| portion | 部分 | | +| positional argument | 位置引數 | | +| prompt | 提示字元 | | +| provisional API | 暫行 API | | +| provisional package | 暫行套件 | | +| Pythonic | Python 風格的 | | +| qualified name | 限定名稱 | | +| reference count | 參照計數 | | +| regular expression | 正規表示式 | | +| regular package | 正規套件 | | +| resolve | 解析 | | +| return | 回傳 | | +| runtime | runtime（不翻譯） | | +| sequence | 序列 | | +| set | set、集合 | | +| set comprehension | 集合綜合運算 | | +| signature | 簽名 | | +| single dispatch | 單一調度 | | +| slice | 切片 | | +| soft deprecated | 軟性棄用 | | +| spec | 規格 | | +| special method | 特殊方法 | | +| specification | 規格 | | +| statement | 陳述式 | | +| static type checker | 靜態型別檢查器 | | +| stdlib | 標準函式庫 | | +| strong reference | 強參照 | | +| t-string | t 字串 | | +| t-strings | t 字串 | | +| text encoding | 文字編碼 | | +| text file | 文字檔案 | | +| triple-quoted string | 三引號內字串 | | +| type | 型別 | | +| type alias | 型別別名 | | +| type hint | 型別提示 | | +| universal newlines | 通用換行字元 | | +| variable annotation | 變數註釋 | | +| virtual environment | 虛擬環境 | | +| virtual machine | 虛擬機器 | | +| visit | 瀏覽 | | +| walrus operator | 海象運算子 | | +| Zen of Python | Python 之禪 | | diff --git a/.claude/skills/validate-translation/SKILL.md b/.claude/skills/validate-translation/SKILL.md new file mode 100644 index 0000000000..77b8fc19ec --- /dev/null +++ b/.claude/skills/validate-translation/SKILL.md @@ -0,0 +1,58 @@ +--- +name: validate-translation +description: Reviews translated PO entries for quality, checking terminology, punctuation, reST syntax, and line length. Use to validate existing translations. +argument-hint: +--- + +# review-translation + +Validate translated PO entries against project rules and report issues. + +## What to Check + +### 1. Terminology Consistency +- Compare terms against `glossary.po` and terminology dictionary +- Flag zh_CN terms that should be zh_TW (see `references/validation-rules.md`) +- Check for inconsistent translations of the same term + +### 2. Punctuation Rules +- Chinese text must use full-width: `「」（）、，。：；！？` +- English text must use half-width: `(),.;:!?` +- Brackets: Full-width if content has Chinese, half-width if English-only + +### 3. CJK-Latin Spacing +- Space required between Chinese and Latin characters +- No space between Latin and Chinese punctuation/symbols + +### 4. reST Syntax Preservation +- All `:role:` syntax must be intact +- Link URLs must be unchanged +- `::` markers must be preserved +- Check for missing `\\ ` escapes before roles + +### 5. Line Length +- Maximum 79 characters per line +- Multi-line format for longer content + +## Review Process + +1. **Parse PO file** - Extract msgid/msgstr pairs +2. **Check each entry** - Apply all validation rules +3. **Categorize issues** - ERROR (must fix), WARNING (should fix), INFO +4. **Generate report** - List issues with line numbers and suggestions + +## Issue Severity + +| Severity | Description | Examples | +|----------|-------------|----------| +| ERROR | Must fix before merge | Broken reST, missing translation | +| WARNING | Should fix | Wrong terminology, spacing issues | +| INFO | Optional improvement | Inefficient line wrapping | + +## Quick Validation Commands + +After review, run: `make lint`, `make wrap`, `make build .po` + +## References + +- `references/validation-rules.md` - Complete validation checklist diff --git a/.claude/skills/validate-translation/references/validation-rules.md b/.claude/skills/validate-translation/references/validation-rules.md new file mode 100644 index 0000000000..cacad0219d --- /dev/null +++ b/.claude/skills/validate-translation/references/validation-rules.md @@ -0,0 +1,128 @@ +# Validation Rules + +Complete checklist for reviewing translations. + +## Structural Checks + +| Check | Severity | Description | +|-------|----------|-------------| +| Empty msgstr | ERROR | Translation missing | +| msgid modified | ERROR | Source text was changed (never modify) | +| Invalid PO syntax | ERROR | Malformed PO entry | +| Obsolete entry | WARNING | Entry marked obsolete | + +## Punctuation Checks + +| Check | Severity | Pattern | +|-------|----------|---------| +| Half-width in Chinese | ERROR | `,` `.` `;` `:` in Chinese text | +| Full-width in English | WARNING | `，` `。` `；` `：` in English text | +| Mismatched quotes | ERROR | `「` without `」` or vice versa | +| Mismatched parens | ERROR | `（` without `）` or vice versa | + +### Punctuation Rules + +**Chinese text uses:** +- Quotes: `「」`（single）`『』`（nested） +- Parentheses: `（）` +- Comma: `，` +- Period: `。` +- Colon: `：` +- Semicolon: `；` +- Exclamation: `！` +- Question: `？` +- List separator: `、` + +**English text uses:** +- Standard ASCII punctuation + +## Spacing Checks + +| Check | Severity | Pattern | +|-------|----------|---------| +| Missing CJK-Latin space | WARNING | Chinese directly adjacent to Latin | +| Extra space | INFO | Multiple consecutive spaces | +| Trailing space | WARNING | Space at end of line | + +### Correct Examples +- `"使用 CPU 運算"` - space between CJK and Latin +- `"使用「CPU」運算"` - no space with symbols + +## Line Length Checks + +| Check | Severity | Threshold | +|-------|----------|-----------| +| Line too long | ERROR | > 79 characters | +| Inefficient wrapping | INFO | Could be better wrapped | + +## reST Syntax Checks + +| Check | Severity | Description | +|-------|----------|-------------| +| Role broken | ERROR | `:role:` syntax malformed | +| Link broken | ERROR | Link syntax malformed | +| Missing backslash | WARNING | CJK adjacent to role without `\\ ` | +| Directive changed | ERROR | Directive name/args modified | +| URL modified | ERROR | Link URL was changed | +| `::` marker removed | ERROR | Code block marker deleted | + +## Terminology Checks + +| Check | Severity | Description | +|-------|----------|-------------| +| Forbidden zh_CN term | ERROR | Uses Simplified Chinese term | +| Wrong glossary term | WARNING | Term differs from glossary | +| Inconsistent term | WARNING | Same term translated differently | + +### Top Forbidden Terms (zh_CN -> zh_TW) + +| Forbidden | Required | +|-----------|----------| +| 函數 | 函式 | +| 返回 | 回傳 | +| 對象 | 物件 | +| 迭代 | 疊代 | +| 創建 | 建立 | +| 代碼 | 程式碼 | +| 信息 | 資訊 | +| 異常 | 例外 | +| 默認 | 預設 | +| 調用 | 呼叫 | + +## Output Format + +Report validation results in this format: + +``` +=== Validation: library/functions.po === + +Entry #42 (line 156): + msgid: "This function returns an iterator." + msgstr: "此函數返回一個迭代器。" + + [ERROR] Terminology: "函數" should be "函式" + [WARNING] Terminology: "返回" should be "回傳" + [WARNING] Terminology: "迭代器" should be "疊代器" + +Summary: 1 error, 2 warnings +``` + +## Common Fixes + +| Issue | Before | After | +|-------|--------|-------| +| zh_CN term | 函數 | 函式 | +| zh_CN term | 返回 | 回傳 | +| zh_CN term | 對象 | 物件 | +| Missing space | 使用CPU | 使用 CPU | +| Wrong punctuation | 例如, | 例如， | +| Missing escape | 參閱:mod:`os` | 參閱\\ :mod:`os` | + +## Validation Commands + +```bash +make lint # sphinx-lint for reST +make wrap # powrap for line length +make build .po # Test Sphinx build +make all # Full documentation build +``` diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 0000000000..3c3dea0e5d --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,112 @@ +# Repository Guidelines + +## Project Structure & Module Organization +This repo contains Traditional Chinese translations of the Python docs. The +content is organized as `.po` files at the root and within topic folders such +as `library/`, `tutorial/`, `reference/`, `c-api/`, and `using/`. Terminology +references live in `glossary.po`, and overall workflow guidance is in +`README.rst`. There is no application source code; most changes are to `.po` +files and translation metadata. + +## Build, Test, and Development Commands +- `make all` builds the full docs with Sphinx and validates rST syntax. It may + clone CPython into a sibling `../cpython` directory if missing. +- `make lint` runs a quick rST syntax check without a full build. +- `make build path/to/file.po` builds a single translation file (faster for + spot-checking). +- `pre-commit install` enables PO-format checks at commit time (recommended). + +## Coding Style & Naming Conventions +- Only edit `msgstr`; do not change `msgid`. +- Keep PO lines <= 79 chars (Poedit or `powrap` can wrap). +- Preserve rST roles, directives, and link targets exactly. +- Follow the project glossary and translation rules (see `glossary.po` and the + project wiki). +- Branch names typically mirror the file path, e.g., `library/math`. + +## Testing Guidelines +There is no unit test suite. Validate changes by running `make lint` or +`make all` and ensuring there are no warnings. If you build a specific file, +confirm the generated HTML in `../cpython/Doc/build/html`. + +## Commit & Pull Request Guidelines +- Open an issue to claim a translation task before starting. +- Base your branch on `upstream/3.13`. +- Use clear commit messages; the repo example is + `Working on path/to/file.po`. +- In PRs, summarize the files translated, link the issue, and note any build + checks you ran (e.g., `make lint`). + +## Agent-Specific Instructions + +### Available Skills +Use these skills located in `.claude/skills/` and project root: + +| Skill | Location | When to Use | +|-------|----------|-------------| +| `doc-translate` | `doc-translate/SKILL.md` | General EN->zh_TW translation rules | +| `rst-translate` | `rst-translate/SKILL.md` | Strings with reST syntax | +| `translate-po` | `.claude/skills/translate-po.md` | Core translation workflow | +| `validate-translation` | `.claude/skills/validate-translation.md` | After translating, validate quality | +| `terminology-check` | `.claude/skills/terminology-check.md` | Check terminology consistency | + +### Translator Agent +**Purpose:** Translate PO file entries with full context awareness. + +**Workflow:** +1. Read the target PO file and identify untranslated entries +2. For each entry, use `translate-po` skill +3. Apply `terminology-check` for consistency +4. Validate with `validate-translation` +5. Save with proper formatting (79 char lines) + +**Invocation:** When asked to translate a PO file or entries. + +### Reviewer Agent +**Purpose:** Review existing translations, especially fuzzy entries. + +**Workflow:** +1. Find fuzzy entries with `make fuzzy` or grep for `#, fuzzy` +2. For each fuzzy entry: + - Compare msgid changes (check translator comments) + - Update msgstr to match new msgid + - Apply `terminology-check` for zh_CN variants + - Validate with `validate-translation` +3. Remove fuzzy flag after review +4. Run `make lint` to verify + +**Invocation:** When asked to review translations or fix fuzzy entries. + +### Quality Agent +**Purpose:** Comprehensive quality assurance for translations. + +**Workflow:** +1. Run `validate-translation` on target files +2. Run `terminology-check` for consistency +3. Check reST syntax with `make lint` +4. Generate quality report with issues found +5. Prioritize fixes by severity (ERROR > WARNING > INFO) + +**Invocation:** When asked to check translation quality or before PR. + +## Quick Reference + +### Translation Rules Summary +- Chinese: full-width punctuation `「」（）、，。` +- English: half-width punctuation `(),.;:!?` +- Spacing: add space between CJK and Latin text +- Lines: max 79 characters +- High-freq terms stay English: `int`, `str`, `list`, `dict`, `iterator`, `generator` + +### Common zh_CN -> zh_TW Fixes +``` +函數 -> 函式 對象 -> 物件 返回 -> 回傳 +模塊 -> 模組 字符串 -> 字串 迭代 -> 疊代 +調用 -> 呼叫 內存 -> 記憶體 異步 -> 非同步 +``` + +### reST Escaping +``` +CJK before role: 參閱\\ :mod:`os` +CJK after link: `連結 `_\\ 中 +``` diff --git a/.codex/skills b/.codex/skills new file mode 120000 index 0000000000..454b8427cd --- /dev/null +++ b/.codex/skills @@ -0,0 +1 @@ +../.claude/skills \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..94332f64b1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# Python Documentation Traditional Chinese Translation + +This project translates Python 3.14 official documentation to Traditional Chinese (zh_TW). + +## Build Commands + +```bash +make all # Build all documentation +make build .po # Build single file (e.g., make build howto/logging.po) +make lint # Check reST syntax with sphinx-lint +make wrap # Format PO files with powrap (max 79 chars) +make fuzzy # List entries marked as fuzzy +make progress # Check translation progress +``` + +## Translation Conventions + +### Punctuation +- **Chinese text:** Full-width punctuation - 「」（）、，。：；！？ +- **English text:** Half-width punctuation - (),.;:!? + +### CJK-Latin Spacing +- Add space between Chinese and Latin: "使用 CPU 運算" (correct) +- No space when adjacent to symbols: "使用「CPU」運算" (correct) + +### Terminology +- class -> 類別 | function -> 函式 | method -> 方法 +- module -> 模組 | argument -> 引數 | parameter -> 參數 +- decorator -> 裝飾器 | iterator -> 疊代器 + +### Keep in English +`int`, `float`, `str`, `bytes`, `list`, `tuple`, `dict`, `set`, `iterator`, `generator`, `pickle` + +### reST Syntax +- Preserve `:mod:`, `:func:`, `:class:`, `:term:`, `:ref:`, `:pep:` roles +- Use `\\ ` as zero-width separator when Chinese precedes reST syntax + +## Key Resources + +- **Terminology:** `focused_terminology_dictionary.csv`, `glossary.po` +- **zh_CN corrections:** `.scripts/google_translate/utils.py` +- **Full guidelines:** `README.rst` (lines 240-377) +- **Skills:** `.claude/skills/` for detailed translation workflows