Skip to content

[Task]: Check the website's en and zh docs with the shared lint-config translation check #313

Open

Description

@PerfectPan

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 与 summarize
  • connection/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

  1. 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="…".
  2. Restore the English comment in the first code block of zh/connection/harness.mdx.
  3. Add a check script (the catalog is on @perfectpan/lint-config v0.9.1 since chore(deps): bump lint-config to v0.9.1 #316) to the scripts project that calls runDocTranslations with 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.
  4. 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 a source-blob: <hash> key (--write adds it), and fumadocs' default page schema (a zod z.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

  1. added
    taskMaintenance, refactoring, dependency, or tooling work
    on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    taskMaintenance, refactoring, dependency, or tooling work

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions