20260910-0137-chinese-first-docs Make the documentation Chinese-first

• status: completed
• createdAt: 2026-09-10 01:37
• approvedAt: 2026-09-10 01:40
• relatedTask: 20260910-0137-chinese-first-docs

Context

The corpus is currently English-first: X.md is English, X.md is its Chinese mirror served under / via the rewrites rule, and .vitepress/links.mts exists solely to re-target relative links across that rewrite. Coverage is uneven:

Group	Count	Words
English + Chinese mirror	35 pairs	—
Chinese only (.md, no English)	15	—
English only, needs translation	82	~69,800

All 82 untranslated files live under bizplan/research/: 27 in vendors/, 39 in air-key-vendors/, 16 reports at the research root. docs/ is excluded by the user's decision.

Proposal

Target shape

• bizplan/**/X.md is Chinese and is the only version.
• bizplan/BUSINESS-PLAN.md is Chinese; bizplan/BUSINESS-PLAN.en.md is the English version, rewritten to /en/business-plan.
• No .md file survives.

Step 1 — promote existing Chinese (no translation)

• 34 pairs: delete X.md, git mv X.md X.md.
• BUSINESS-PLAN: git mv BUSINESS-PLAN.md BUSINESS-PLAN.en.md, then git mv BUSINESS-PLAN.md BUSINESS-PLAN.md.
• 15 Chinese-only files: git mv X.md X.md.

Step 2 — translate the 82 English-only files, in three batches

1. 16 research reports (~43k words) — longest first.
2. 27 vendors/ files (~14k words).
3. 39 air-key-vendors/ files (~13k words).

Translation rules, fixed before batch 1 starts:

• Company names, product names, model numbers, standards (IEC/ISO/ABYC), interface names (CAN FD, NMEA 2000, LIN) and units stay in their original form.
• Tables keep their structure; numbers, currencies and dates are copied, never recomputed.
• Code blocks, link targets and image paths are untouched.
• Each batch ends with bun run docs:build and a diff review before the next starts.

The English original is replaced in place, not kept alongside; history stays in git.

Step 3 — collapse the bilingual machinery

• .vitepress/config.mts: drop locales, drop the .md -> zh/ rewrites rule, drop the sharedSearchIndex plugin (it only existed to merge the two locale search indexes), keep a single Chinese theme configuration, and add a rewrite for BUSINESS-PLAN.en.md -> /en/business-plan.
• Delete .vitepress/links.mts.
• Strip mirror links ([zh](...), "Mirror" columns) from index pages and rewrite every remaining .md reference to .md.

Risks

• Translation is irreversible in the working tree; the English text survives only in git history.
• Terminology drift across 82 files is the main quality risk; the fixed rules above plus a per-batch diff review are the control.
• Numbers and model codes inside long research tables are the highest-value thing to get wrong — they are copied verbatim, never re-derived.
• Volume: ~70k words of translation cannot land in one pass; the batches are the unit of delivery, and the site stays buildable between them.

Scope

• Renamed: 50 files (35 pairs promoted, 15 Chinese-only).
• Rewritten: 82 research files translated into Chinese.
• Modified: .vitepress/config.mts, index pages carrying mirror links.
• Deleted: 34 English originals with mirrors, .vitepress/links.mts.
• Untouched: docs/** (PMA tracking stays English).

Alternatives

• Keep the English originals as X.en.md alongside the Chinese: rejected — the instruction is that only BUSINESS-PLAN keeps an English version.
• Translate only the research reports and leave vendor catalogues in English: rejected by the user's answer ("translate everything").

Progress

• 2026-09-10: steps 1 and 3 are done. 35 pairs promoted, 15 Chinese-only files renamed, BUSINESS-PLAN.en.md split out, 473 .zh.md references and 4 /zh/ links rewritten, and the locale machinery removed (locales, rewrites, the shared search index plugin, links.mts). BUSINESS-PLAN.en.md is served at /bizplan/BUSINESS-PLAN.en rather than a rewritten /en/business-plan: no rewrite means its relative links keep resolving without a link-rewriting plugin, which is exactly what was just deleted.
• 2026-09-10: step 2 is done. 79 files were translated, not 82: 01-market-size, 02-competitors and 03-certification-tech-trends were already Chinese despite lacking a .zh suffix. Batches: 13 research reports, 27 PDM vendor catalogues, 39 Air/Key vendor catalogues. Company names, model numbers, standards, interface names, units, prices, table structure and link targets were carried over verbatim. bizplan/ now contains no English document except BUSINESS-PLAN.en.md.