ADR-0010: EN-Source + Auto-Translated ZH Bilingual Strategy

Status: ACCEPTED Date: 2026-03-27 Scope: workspace Supersedes: N/A Superseded by: N/A

Context

The platform team operates in a bilingual (English + Chinese) environment. Documentation is needed in both languages for different audiences: English for developers and architecture decisions, Chinese for operations and consumer-facing content. Maintaining two parallel source documents creates synchronization burden and inconsistency risk.

Source: Documentation system standard (2026-03-27-documentation-system-standard.md, Language Policy section)

Decision

English is the source language for all documentation. Operational and consumer-facing documents (RUNBOOK, ENV-CONFIG, MODULE-SPEC) receive auto-translated Chinese versions. Architecture and design documents (ADR, DESIGN, SPEC, PLAN) remain English-only. The bilingual convention is: DOCUMENT.md (English source) + DOCUMENT.zh.md (Chinese translation) in the same directory.

Consequences

• Single source of truth per document (English), eliminating dual-maintenance.
• Operational teams get Chinese documentation for day-to-day work (runbooks, environment configuration).
• Translation can be automated (LLM-assisted) with human review for accuracy.
• ADRs and design specs are English-only, which is acceptable since their audience is developers who work in English.
• Adding a third language in the future follows the same pattern (.ja.md, .ko.md, etc.).

Alternatives Considered

• Chinese source with English translation: Rejected because the codebase, commit messages, and API contracts are all in English; Chinese-source documentation would create a language mismatch.
• Fully bilingual (dual source): Rejected because maintaining two authoritative versions leads to drift and doubles the review burden.
• English-only everywhere: Rejected because operational teams benefit significantly from Chinese runbooks and configuration guides.