Add agent guidelines and translation skills

Author: ken71301

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.

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