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.

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 tracked pages​

website/i18n/translation-policy.json contains the machine-readable list of pages whose Chinese mirrors are required. Required pages must exist, remain current, and build successfully. Changes to that list require the canonical page, Chinese mirror, and policy verification to change together.

All other active public pages are tracked when a Chinese mirror exists. A missing tracked mirror is allowed during incremental rollout. An existing tracked mirror must either be current or explicitly stale; silent drift is forbidden.

Generated API reference, archived evidence, and temporary execution plans remain English-only by default. Chinese guides link to generated API reference instead of copying it.

Marking a tracked translation stale​

When a tracked Chinese mirror cannot be updated with its canonical source:

  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. Required pages cannot use this escape hatch.

Change workflow​

For every canonical public documentation change:

  1. update and verify the English source;
  2. identify whether the page is required, tracked, or English-only;
  3. update and review the Chinese mirror in the same pull request when required;
  4. for a tracked mirror, either update it or mark it stale in the same pull request;
  5. state localization impact in the pull request template;
  6. run the translation verifier and build both locales.

Urgent correctness and security fixes still update English first. If a tracked translation cannot be corrected in the urgent pull request, mark it stale. Do not leave known inaccurate text presented as current.

Commands​

From website/:

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

write-translations adds missing Docusaurus JSON message entries without replacing reviewed translations. 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.

Repository-level documentation placement and links remain covered by:

./gradlew verifyDocumentationStructure

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.
  • 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.