Skip to main content

Documentation Localization Workflow

This page is the operational contract for maintaining ViewCompose documentation in English and Simplified Chinese. The canonical language and enforcement policy are defined in Documentation Governance.

Source layout​

English is the canonical source and remains under docs/. Simplified Chinese mirrors use the standard Docusaurus locale tree:

docs/<path>.md
website/i18n/zh-CN/docusaurus-plugin-content-docs/current/<path>.md

The English site is published at /; the Chinese site is published at /zh-CN/. Keep the same relative path and document ID in both locales so the language switcher preserves reader context. Navigation, footer, and React-page messages live in the other standard website/i18n/zh-CN/ translation files generated by Docusaurus.

Within a Chinese mirror, use a relative Markdown link only when the target also has a Chinese mirror. Link untranslated targets through their complete canonical public URL, such as https://docs.viewcompose.com/architecture/overview, so the link also works on GitHub, strict link checking remains valid, and the reader intentionally enters the English source. Replace that URL with the locale-relative Markdown link when its reviewed Chinese mirror is added.

Canonical English documents always keep repository-relative Markdown links. During a localized build, Docusaurus can render an untranslated English fallback page beside translated targets. The site's Markdown resolver rewrites only those verified cross-boundary links to the target's public route. It does not suppress or downgrade unknown broken links.

Canonical titles, headings, and narrative prose are English. Chinese-mirror titles, headings, and narrative prose are Simplified Chinese. Code fences, inline identifiers, commands, URLs, and real UI literals keep their exact source language. Format a foreign-language UI literal in narrative as inline code; do not use an unmarked foreign-language sentence as an example. Historical archives and temporary execution plans are excluded from the locale tree.

Page front matter​

Every Chinese Markdown mirror must declare:

---
translation_source: project/localization.md
translation_source_hash: <sha256-of-canonical-source>
translation_status: current
---

translation_source is relative to docs/. translation_source_hash records the exact canonical content that was reviewed. translation_status is either current or stale.

Do not update the hash as a mechanical response to a failing build. Read the English change, update the Chinese meaning, verify links and examples, and only then record the new fingerprint.

Required and English-only pages​

website/i18n/translation-policy.json contains the machine-readable list of active handwritten public pages. Every listed Chinese mirror must exist, use Chinese narrative, remain current, and build successfully. Adding, moving, or removing a public page requires the canonical page, Chinese mirror, policy, and verification to change together.

Generated API reference, immutable historical module-manual snapshots, archived evidence, temporary execution plans, and internal evidence not published as user guidance remain English-only. Chinese guides link to generated API reference instead of copying it. Locale fallback must not be used to publish a new active handwritten page without a reviewed Chinese mirror.

Recovering a stale translation​

The verifier still understands an explicit stale marker for historical recovery, but every active public page is required and therefore cannot merge in that state. During repair:

  1. set translation_status: stale;
  2. keep translation_source_hash at the last reviewed canonical fingerprint;
  3. add the visible marker immediately after front matter:
:::warning Translation status
This Chinese translation is behind the canonical English page. Use the English version for the
latest contract.
:::

Use the equivalent Chinese warning in the translated page. Before merge, update the Chinese meaning, set translation_status: current, and record the reviewed canonical fingerprint. Do not use the marker as an escape hatch for a required page.

Change workflow​

For every canonical public documentation change:

  1. update and verify the English source;
  2. identify whether the page is public or deliberately English-only;
  3. update and review the Chinese mirror in the same pull request for every public page;
  4. verify that narrative uses the directory language while literals remain exact;
  5. state localization impact in the pull request template;
  6. run the canonical repository documentation gate and the both-locale build.

Urgent correctness and security fixes still update English first within the change. Do not merge a public page while its Chinese mirror is missing, stale, or knowingly inaccurate.

Commands​

After the Chinese meaning has been reviewed, update only the explicitly reviewed mirrors from website/ with paths relative to docs/:

npm run mark:translations-reviewed -- architecture/overview.md guides/theming.md

The command validates the source mapping and current status before recording the canonical fingerprint. It is an explicit review acknowledgment, not an automatic step and not a substitute for updating the Chinese meaning.

Use these lower-level website commands when diagnosing the documentation site:

npm run write-translations
npm run verify:languages
npm run verify:translations
npm run typecheck
npm run build

write-translations adds missing Docusaurus JSON message entries without replacing reviewed translations. verify:languages rejects Han narrative in canonical pages and checks every Chinese title, heading, and prose block independently; a long translated page cannot hide one misplaced English section behind a page-wide language ratio. Code, identifiers, commands, URLs, and marked literals remain excluded. verify:translations validates source mapping, required coverage, fingerprints, status, and stale-warning markers. build produces both en and zh-CN sites and keeps strict broken-link checking enabled.

The canonical repository gate is:

./gradlew verifyDocumentationStructure

It runs the documentation script tests, language classifier, translation coverage and fingerprint verifier, placement checks, and link checks. qaQuick depends on this task, so the same freshness contract is enforced locally and in the main CI before the website build.

Review checklist​

  • Technical behavior and terminology match the canonical page.
  • Code, commands, coordinates, identifiers, and URLs were not translated incorrectly.
  • Relative links resolve in the localized route.
  • Screenshots are localized or explicitly language-neutral.
  • The source fingerprint represents the English content actually reviewed.
  • A stale translation contains the visible warning and is not a required page.
  • Canonical and Chinese titles, every heading, and each narrative block match their directory language.
  • Both locales build successfully.

AI-assisted translation​

AI may draft or update a translation, but it must follow the same page-level workflow. Before changing a mirror, read the current canonical source, the existing translation, and this page. Preserve technical identifiers and validate examples against code or tests. Never claim a translation is current merely because its fingerprint was regenerated.