Skip to content

docs: add Chinese reading copies of the guide, reference, architecture, and setup docs - #149

Merged
PerfectPan merged 3 commits into
mainfrom
docs/zh-cn-reading-copies
Nov 17, 2026
Merged

PerfectPan merged 3 commits into
mainfrom
docs/zh-cn-reading-copies

Conversation

@PerfectPan

Copy link
Copy Markdown
Owner

Summary

  • Add Chinese reading copies (*.zh-CN.md) of every document in docs/guide/, docs/reference/, docs/architecture/, and docs/development/ (14 files), and point README.zh-CN.md at them. Terms follow the UI glossary in apps/web/src/i18n/dictionary.zh-CN.ts, UI labels are quoted as the Chinese UI shows them, and credential tokens are 令牌.
  • Widen the bilingual rule to those directories: CONTRIBUTING.md's two sections become Bilingual Documentation; AGENTS.md and the Spec and Plan READMEs follow.
  • Replace the local scripts/check-doc-translations.mjs with the shared check from @perfectpan/lint-config/doc-translations (v0.9.0, feat(doc-translations): share the translated Markdown check lint-config#13). Besides the pairing, the first line, and code blocks, it now compares headings in order, tables, list items, links (a link to a translated document must point to its copy) and anchors, and each copy carries a <!-- source-blob: <hash> --> stamp of the English file it was checked against, so editing an English file fails until its copy follows and is recorded with --write.
  • Correct six English statements that disagreed with the code, found while translating: the bundled agent-kit version (0.24.1 → 0.25.0), that only the ATIF export fails on a trace with nothing to export, the default export file name, that only user and agent steps carry is_copied_context, and which cut (80 or 500 characters) applies to titles and to first prompts.

Validation

  • node scripts/check-doc-translations.mjs: doc-translations: ok (15 pairs). Editing one English file (docs/guide/mcp.md) made it fail with changed since this translation was recorded (git show cff4d0f5a0f3 …); restoring the file passed again.
  • The pre-commit hook on the final commit: gh repo-checks repository --staged, check-doc-translations, check-conventions (452 files), check-layers (8 projects), format.mjs --check, lint-scripts.mjs all passed.
  • pnpm lint and pnpm typecheck with lint-config v0.9.0: passed.
  • pnpm-lock.yaml changes only the lint-config resolution (21d4b41 → 1dcf174, the v0.9.0 tag). pnpm install warns about a missing vite peer in apps/web and unapproved build scripts; both appear identically on main.
  • Translation review: two reviewer passes over all 15 pairs against the English and the code; the first found four meaning errors (NO_COLOR, what Estela never writes, the Ready line, the CI report) and smaller drifts, all fixed; the second confirmed those fixes and the six English corrections against the code, and checked every stamp with git hash-object.
  • No changeset: documentation, root scripts, and a devDependency only; docs/reference/public-interface.md is unchanged.
  • Not run locally: pnpm test, pnpm build, check-browser-bundle.mjs, check-budgets.mjs — nothing under apps/ or packages/ changed except Markdown; CI runs them.

Risks

  • Every English edit to these 15 documents now needs its Chinese copy updated and recorded in the same PR, or CI fails; git show <hash> from the stamp prints the English text the copy last matched.
  • The structure check cannot tell whether the Chinese says the same thing; reviewers still compare the prose.

PerfectPan and others added 3 commits November 17, 2026 22:30
Widen the bilingual rule from the README, Specs, and Plans to the user
guide, reference, architecture, and development docs, and check the
copies with @perfectpan/lint-config/doc-translations (v0.9.0) instead of
a local script: headings, code blocks, tables, list items, links and
anchors in order, plus a source-blob stamp in each copy so that an
edited English file fails until its copy is updated and recorded with
--write.

Correct six English statements that disagreed with the code: the bundled
agent-kit version, which export fails on an empty trace, the default
export file name, which ATIF steps carry is_copied_context, and which
cut (80 or 500 characters) applies to titles and first prompts. Fix the
review findings in the Chinese copies (NO_COLOR, what Estela never
writes, the Ready line, the CI report, credential tokens as 令牌, and
smaller drifts), and record all 15 stamps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@PerfectPan
PerfectPan merged commit d121c89 into main Nov 17, 2026
7 checks passed
@PerfectPan
PerfectPan deleted the docs/zh-cn-reading-copies branch November 17, 2026 15:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant