diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..5b96529180 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# 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 +- Use the local skills when translating: `doc-translate/` for general rules + and `rst-translate/` when strings include rST syntax. 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： ::" +```