Repository navigation
Description
Problem
The website keeps every page in apps/website/content/docs/en and apps/website/content/docs/zh (24 tracked files each, 20 .mdx pairs). The trees match today, but no check keeps a page and its translation in step: structure, code, links, and anchors can drift, and an English edit without the Chinese one passes. Only the landing copy has a test (copy.test.ts).
@perfectpan/lint-config v0.9.0 ships a shared check for translated Markdown, @perfectpan/lint-config/doc-translations, already used by PerfectPan/estela (PerfectPan/estela#149). A read-only run on main (6b18626) with sources: ["apps/website/content/docs/en/**/*.mdx"], translations: ["apps/website/content/docs/zh/**/*.mdx"], exclude: ["apps/website/content/docs/en/api/**"] and the /docs/en/ → /docs/zh/ mapping finds 20 pairs and 5 problems, all one kind: the Chinese pages translate the title="…" of a code block, which the check compares as part of the info string.
connection/cost.mdx:ts title="createPricing and summarize"→createPricing 与 summarizeconnection/harness.mdx:ts title="planInstall and applyInstall"connection/sessions.mdx:ts title="List sessions and load one transcript"connection/token-usage.mdx:ts title="Decode one agent's usage sources"installation.mdx:bash title="Install @rivus/agent-kit"
These titles are captions a reader sees, so translating them is right; the check is what needs to change. lint-config v0.9.1 compares only a code block's language and body. With it the same run reports 1 problem, which the title report on that page had hidden:
connection/harness.mdx: the three-line comment in the first code block (en line 33) is translated. Code blocks stay as written in both languages, as in PerfectPan/rivus-agent#447: a translated block cannot be compared, so drift inside it goes unnoticed. If the Chinese reader needs the explanation, it goes in the text around the block.
Proposed Solution
- Done in lint-config v0.9.1: only a code fence's language (the first word of the info string) is compared, not its meta such as
title="…". - Restore the English comment in the first code block of
zh/connection/harness.mdx. - Add a check script (the catalog is on
@perfectpan/lint-configv0.9.1since chore(deps): bump lint-config to v0.9.1 #316) to thescriptsproject that callsrunDocTranslationswith the configuration above, run in CI and the pre-commit hook.content/docs/en/api/is TypeDoc output (gitignored) whose Chinese pages fall back to English by design, so it stays excluded. - Decide whether to turn on
stamp: true, so that an English page edited without its Chinese page fails until the pair is recorded again. Since v0.9.1, a translation with frontmatter keeps the stamp there as asource-blob: <hash>key (--writeadds it), and fumadocs' default page schema (a zodz.object) strips the key, so the pages build unchanged. Frontmatter is not compared.
The check verifies #fragment links only when they point to a .md file, so the fragment links in these pages (#价格快照, /docs/connection/cost#价格快照) are not checked.
Acceptance Criteria
- The check runs in CI and the pre-commit hook and reports no problems on
main, with the generated API pages excluded. - Code block titles may be translated; code bodies (comments included), headings, tables, lists, and links must match.
- The website docs or CONTRIBUTING.md say how a page and its translation are kept in step.
Activity