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/terminology-check.md b/.claude/skills/terminology-check.md new file mode 100644 index 0000000000..49987438de --- /dev/null +++ b/.claude/skills/terminology-check.md @@ -0,0 +1,170 @@ +--- +name: terminology-check +description: Check and enforce terminology consistency based on project glossary. Identifies zh_CN variants and suggests zh_TW corrections. +metadata: + short-description: Terminology consistency checker +--- + +# terminology-check + +## Scope +- Check terminology against project glossary +- Identify zh_CN to zh_TW conversion needs +- Track term usage consistency across files +- Suggest standardized translations + +## Terminology Sources + +### Primary: glossary.po +Official Python glossary translations at project root. + +### Secondary: terminology.md +Quick reference at `doc-translate/references/terminology.md`. + +### Tertiary: Built-in Mapping +Common zh_CN to zh_TW corrections (from `.scripts/google_translate/utils.py`). + +## Forbidden Terms (zh_CN -> zh_TW) + +These Simplified Chinese terms MUST be converted: + +| Forbidden | Required | English | +|-----------|----------|---------| +| 創建 | 建立 | create | +| 代碼 | 程式碼 | code | +| 信息 | 資訊 | information | +| 模塊 | 模組 | module | +| 標誌 | 旗標 | flag | +| 異常 | 例外 | exception | +| 解釋器 | 直譯器 | interpreter | +| 頭文件 | 標頭檔 | header | +| 對象 | 物件 | object | +| 支持 | 支援 | support | +| 默認 | 預設 | default | +| 兼容 | 相容 | compatible | +| 字符串 | 字串 | string | +| 宏 | 巨集 | macro | +| 描述符 | 描述器 | descriptor | +| 字節 | 位元組 | bytes | +| 緩存 | 快取 | cache | +| 調用 | 呼叫 | call | +| 哈希 | 雜湊 | hash | +| 類型 | 型別 | type | +| 子類 | 子類別 | subclass | +| 實現 | 實作 | implement | +| 數據 | 資料 | data | +| 返回 | 回傳 | return | +| 指針 | 指標 | pointer | +| 字段 | 欄位 | field | +| 擴展 | 擴充 | extension | +| 遞歸 | 遞迴 | recursive | +| 用戶 | 使用者 | user | +| 算法 | 演算法 | algorithm | +| 優化 | 最佳化 | optimize | +| 字符 | 字元 | character | +| 設置 | 設定 | setting | +| 線程 | 執行緒 | thread | +| 進程 | 行程 | process | +| 迭代 | 疊代 | iterate | +| 內存 | 記憶體 | memory | +| 打印 | 印出 | print | +| 異步 | 非同步 | async | +| 調試 | 除錯 | debug | +| 堆棧 | 堆疊 | stack | +| 回調 | 回呼 | callback | +| 公共 | 公開 | public | +| 函數 | 函式 | function | +| 變量 | 變數 | variable | +| 常量 | 常數 | constant | +| 添加 | 新增 | add | +| 轉義 | 跳脫 | escape | +| 基類 | 基底類別 | base class | + +## High-Frequency Terms (Keep in English) + +These terms should NOT be translated, even if glossary has translations: + +``` +int, float, str, bytes, bool +list, tuple, dict, set +iterator, generator, iterable +pickle, module, method +True, False, None +``` + +## Standard Translations + +Core Python terms with required zh_TW translations: + +| English | Traditional Chinese | +|---------|---------------------| +| abstract base class | 抽象基底類別 | +| annotation | 註釋 | +| argument | 引數 | +| attribute | 屬性 | +| callable | 可呼叫物件 | +| class | 類別 | +| closure | 閉包 | +| context manager | 情境管理器 | +| coroutine | 協程 | +| decorator | 裝飾器 | +| descriptor | 描述器 | +| dictionary | 字典 | +| docstring | 說明字串 | +| exception | 例外 | +| expression | 運算式 | +| function | 函式 | +| generator | 產生器 | +| global | 全域 | +| immutable | 不可變物件 | +| import | 引入 | +| instance | 實例 | +| interpreter | 直譯器 | +| iterable | 可疊代物件 | +| iterator | 疊代器 | +| keyword argument | 關鍵字引數 | +| list comprehension | 串列綜合運算 | +| local | 區域 | +| method | 方法 | +| module | 模組 | +| mutable | 可變物件 | +| namespace | 命名空間 | +| object | 物件 | +| package | 套件 | +| parameter | 參數 | +| positional argument | 位置引數 | +| sequence | 序列 | +| slice | 切片 | +| statement | 陳述式 | +| type | 型別 | +| variable | 變數 | + +## Check Process + +1. **Extract terms** - Parse msgstr for Chinese phrases and English words +2. **Check forbidden** - Flag any zh_CN variants from the forbidden list +3. **Check consistency** - Compare with other translations of same term +4. **Check glossary** - Verify against official glossary.po +5. **Report issues** - List violations with suggestions + +## Output Format + +``` +=== Terminology Report: library/functions.po === + +FORBIDDEN TERMS (must fix): + Line 42: "函數" -> "函式" (function) + Line 78: "返回" -> "回傳" (return) + Line 156: "對象" -> "物件" (object) + +INCONSISTENT TERMS (review): + "iterator" translated as: + - "疊代器" (45 occurrences) <- standard + - "迭代器" (3 occurrences) <- zh_CN variant + +Total: 3 forbidden, 1 inconsistent +``` + +## Related Skills +- `doc-translate` - General translation rules +- `validate-translation` - Comprehensive validation diff --git a/.claude/skills/translate-po.md b/.claude/skills/translate-po.md new file mode 100644 index 0000000000..406e6ec329 --- /dev/null +++ b/.claude/skills/translate-po.md @@ -0,0 +1,156 @@ +--- +name: translate-po +description: Core skill for translating PO file entries from English to Traditional Chinese. Orchestrates doc-translate, rst-translate, and terminology-check. +metadata: + short-description: Translate PO entries EN->zh_TW +--- + +# translate-po + +## Scope +- Translate English PO msgid entries to Traditional Chinese msgstr +- Apply all formatting, punctuation, and spacing rules +- Preserve reStructuredText syntax exactly +- Maintain terminology consistency with glossary +- Mark uncertain translations with fuzzy flag + +## Prerequisites + +Before translating, always: +1. Read the full msgid to understand context +2. Check msgctxt for additional context if present +3. Review translator comments (#. and #:) +4. Look up unfamiliar terms in glossary references + +## Translation Workflow + +### Step 1: Analyze Content Type + +Identify what you're translating: +- **Pure prose** - No markup, straightforward translation +- **Code-only** - Preserve exactly, do not translate +- **Mixed** - Prose with inline code/roles (most common) +- **reST structural** - Directives, links, complex markup + +### Step 2: Apply Translation Rules + +#### Punctuation +``` +Chinese sentences -> Full-width: 「」（）、，。：；！？ +English sentences -> Half-width: (),.;:!? +``` + +#### Spacing +``` +Add space between CJK and Latin: 使用 CPU 運算 +No space with symbols: 使用「CPU」運算 +``` + +#### Terminology +- Use `terminology-check` skill for reference +- High-frequency terms stay English: int, float, str, list, tuple, dict, iterator, generator +- Follow glossary for standard terms + +### Step 3: Handle reST Syntax + +Use `rst-translate` skill rules: + +#### Roles - Keep syntax, translate display text if needed +``` +:mod:`os` -> :mod:`os` (unchanged) +:term:`iterator` -> :term:`疊代器 ` +:ref:`section-name` -> :ref:`章節名稱 ` +``` + +#### Backslash Escaping +``` +CJK before role: 參閱\\ :mod:`os` +CJK after link: `連結 `_\\ 中 +Full-width after: :term:`object`\\（ +``` + +#### Literal Blocks +``` +msgid "Example::" +msgstr "範例： ::" +``` + +### Step 4: Format Output + +#### Line Wrapping (max 79 chars) +``` +msgstr "" +"第一行翻譯內容" +"第二行繼續翻譯。" +``` + +#### Fuzzy Flag +Add `#, fuzzy` when: +- Translation is uncertain +- Machine-translated content +- Needs human review + +``` +#, fuzzy +msgid "Original text" +msgstr "可能需要審核的翻譯" +``` + +## Quality Checklist + +Before finalizing, verify: +- [ ] Line length <= 79 characters +- [ ] Punctuation rules followed (full-width for Chinese) +- [ ] Spacing rules followed (space between CJK/Latin) +- [ ] reST syntax preserved exactly +- [ ] Terminology consistent with glossary +- [ ] No empty msgstr (unless intentionally skipping) + +## 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:`可變物件 ` 序列。" +``` + +## Related Skills +- `doc-translate` - General translation rules +- `rst-translate` - reST-specific rules +- `terminology-check` - Terminology validation +- `validate-translation` - Post-translation validation + +## References +- Terminology: `doc-translate/references/terminology.md` +- Glossary: `glossary.po` +- Wiki: https://github.com/python/python-docs-zh-tw/wiki/術語列表 diff --git a/.claude/skills/validate-translation.md b/.claude/skills/validate-translation.md new file mode 100644 index 0000000000..a29ab2d661 --- /dev/null +++ b/.claude/skills/validate-translation.md @@ -0,0 +1,100 @@ +--- +name: validate-translation +description: Validate translated PO entries against project rules, terminology, and reST syntax. Use after translating or reviewing translations. +metadata: + short-description: Validate translation quality +--- + +# validate-translation + +## Scope +- Validate existing translations in PO files +- Check formatting, punctuation, spacing, and terminology rules +- Report errors, warnings, and suggestions +- Ensure reST syntax preservation + +## Validation Checklist + +### 1. Structural Checks +| Check | Severity | Description | +|-------|----------|-------------| +| Empty msgstr | ERROR | Translation missing for non-fuzzy entry | +| msgid modified | ERROR | Source text was incorrectly changed | +| Invalid PO syntax | ERROR | Malformed PO entry structure | + +### 2. Punctuation Checks +| Check | Severity | Rule | +|-------|----------|------| +| Half-width in Chinese | ERROR | Chinese text must use `，。；：！？「」（）` | +| Full-width comma/period in English | WARNING | English text should use `,.;:!?()` | +| Mismatched quotes | ERROR | `「` must pair with `」` | +| Mismatched parentheses | ERROR | `（` must pair with `）` | + +### 3. Spacing Checks +| Check | Severity | Rule | +|-------|----------|------| +| Missing CJK-Latin space | WARNING | Add space between Chinese and English text | +| No space before/after symbols | OK | `使用「CPU」運算` is correct | +| Trailing whitespace | WARNING | No trailing spaces in msgstr | + +### 4. Line Length +| Check | Severity | Threshold | +|-------|----------|-----------| +| Line too long | ERROR | > 79 characters per line | + +### 5. reST Syntax Checks +| Check | Severity | Description | +|-------|----------|-------------| +| Role syntax broken | ERROR | `:role:`content`` malformed | +| Role name changed | ERROR | Role type was modified | +| Link target changed | ERROR | URL or reference target modified | +| Missing backslash escape | WARNING | CJK adjacent to role needs `\\ ` | + +### 6. Terminology Checks +| Check | Severity | Description | +|-------|----------|-------------| +| zh_CN term used | WARNING | Simplified Chinese variant detected | +| Inconsistent term | WARNING | Same term translated differently | +| High-freq term translated | INFO | Terms like `int`, `list` should stay English | + +## Validation Process + +1. **Read the PO entry** - Parse msgid, msgstr, comments, and flags +2. **Check structure** - Verify PO syntax is valid +3. **Check punctuation** - Apply Chinese/English punctuation rules +4. **Check spacing** - Verify CJK-Latin spacing +5. **Check line length** - Ensure <= 79 characters +6. **Check reST** - Validate roles, links, escaping +7. **Check terminology** - Cross-reference with glossary + +## Output 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` | + +## Related Skills +- `doc-translate` - General translation rules +- `rst-translate` - reST-specific rules +- `terminology-check` - Detailed terminology validation 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/doc-translate/SKILL.md b/doc-translate/SKILL.md new file mode 100644 index 0000000000..89f4be4d89 --- /dev/null +++ b/doc-translate/SKILL.md @@ -0,0 +1,49 @@ +--- +name: doc-translate +description: Use when translating English content to Traditional Chinese in this repo (python-docs-zh-tw), especially for PO/reStructuredText content. +metadata: + short-description: Translate EN to zh-tw for docs +--- + +# doc-translate + +## Scope +- Translate English documentation to Traditional Chinese for this repo. +- Preserve reStructuredText/PO formatting and links exactly. + +## Workflow +1) Read the full source section before translating to preserve meaning and context. +2) Translate with the rules below; keep PO syntax intact. +3) Check line length (PO), spacing, and punctuation rules. +4) Confirm glossary terms and high-frequency words are handled as specified. + +## Translation Rules +- Chinese sentences use fullwidth punctuation; English sentences keep halfwidth punctuation. + - Example: 「」（）、，。 + - Example: Python is supported by Python Software Foundation (PSF). +- Mixed Chinese/English should include spaces between Chinese and English words; no extra space between English words and symbols. + - Example: 使用 CPU 運算、使用「CPU」運算 +- Proper nouns should follow the glossary translation when available. +- Proper nouns may remain untranslated (e.g., CPU, Unicode). +- For uncommon or uncertain terms, add a parenthetical note or keep the original term; annotate only on first occurrence per page. + - Example: 正規表示式 (regular expression) + - Example: Network News Transfer Protocol、Portable Network Graphics（可攜式網路圖形） +- PO lines should be <= 79 characters (Poedit handles this; `powrap` is optional). +- High-frequency terms should stay in English (even if glossary includes a translation). + - Example: int, float, str, bytes, list, tuple, dict, set, iterator, generator, iterable, pickle + +## Parentheses +- If parentheses contain Chinese, use fullwidth parentheses. +- If parentheses contain only English, use halfwidth parentheses and keep English spacing. + - Example: list（串列）是 Python 中很常見的資料型別。 + - Example: 在本情況使用 zip(*[iter(x)]*n) 是很常見的情況（Python 慣例）。 + - Example: 在超文件標示語言 (HTML) 中應注意跳脫符號。 + +## Related Skills +- Use `rst-translate` when the string includes reStructuredText syntax. + +## References +- Local glossary: `glossary.po` +- Terminology excerpt: `doc-translate/references/terminology.md` +- Term list (wiki): https://github.com/python/python-docs-zh-tw/wiki/%E8%A1%93%E8%AA%9E%E5%88%97%E8%A1%A8 +- Official glossary: https://docs.python.org/zh-tw/3/glossary.html diff --git a/doc-translate/references/terminology.md b/doc-translate/references/terminology.md new file mode 100644 index 0000000000..df7894198d --- /dev/null +++ b/doc-translate/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/rst-translate/SKILL.md b/rst-translate/SKILL.md new file mode 100644 index 0000000000..d17145739a --- /dev/null +++ b/rst-translate/SKILL.md @@ -0,0 +1,68 @@ +--- +name: rst-translate +description: Use when translating strings that include reStructuredText (rST) syntax in this repo. +metadata: + short-description: rST translation rules +--- + +# rst-translate + +## Scope +- Apply rST-specific spacing, escaping, and formatting rules during translation. +- Preserve all rST roles, directives, and link targets exactly. + +## Double Backslash Usage (\\) +Use `\\` to preserve rST-required spacing without rendering a visible space in HTML. + +### When spaces are required for rST parsing +```text +參閱 :mod:`os` 模組 +``` +```text +參閱\\ :mod:`os` 模組 +``` + +### When rST renders Chinese text +```text +一個 :term:`file object`。 +一個\\ :term:`檔案物件 `。 +參考 `wiki 文章 `_\\ 中 +``` + +## Common rST Edge Cases +Fullwidth punctuation (，。： etc.) is fine with rST roles: +```text +一個 :term:`file object`。 +``` + +Fullwidth parentheses require escaping: +```text +一個 :term:`file object`（ # build failed +一個 :term:`file object`\\（ +``` + +## Link Display Text +For inline links with explicit titles, translate the visible text and keep the URL unchanged. +```text +`specification for packages `_ +`套件規格 `_ +``` + +For :ref: with explicit titles, translate the visible text and keep the target unchanged. +```text +:ref:`the remaining cases ` +:ref:`其餘情況 ` +``` + +For :term: with explicit titles, translate the visible text and keep the target unchanged. +```text +:term:`namespace packages ` +:term:`命名空間套件 ` +``` + +## Literal Block Marker (::) +When source ends with `::`, translate to keep `::` while using a fullwidth colon: +```text +msgid "blah blah::" +msgstr "blah blah： ::" +```