Skip to content

AGENTS.md

Latest commit

 

History

History
112 lines (91 loc) · 4.32 KB

AGENTS.md

File metadata and controls

112 lines (91 loc) · 4.32 KB

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:   `連結 <url>`_\\ 中