EPIC(docs): review, partially restructure, and fully localize documentation to Chinese
- Dominant language
- Rust
- Stars
- 41k
- Forks
- 3.6k
- Avg merge
- 13h 59m
- Merged PRs (30d)
- 299
Description
## Why
CodeWhale is a large project with a growing Chinese user base. Many docs under
`docs/` are English-only, which creates a real barrier for Chinese-speaking
users who aren't fluent in English. Machine translation introduces errors, and
worse, several source documents are already stale or carry outdated information.
Maintaining the docs — auditing them, restructuring where needed, and delivering
a complete Chinese localization — is no longer optional.
The Indonesian localization (10 `.id.md` files) already proves the pattern works.
Chinese deserves the same treatment, and the existing `.zh-CN.md` suffix pattern
(two files: `LSP_PHP_CUSTOM.zh-CN.md`, `WINDOWS_BEGINNER.zh-CN.md`) should be
consolidated into a `zh_hans/` folder for discoverability and maintainability.
## Tier 1 — audit and restructure the docs tree
Audit every English doc for freshness, then restructure the tree so translated
docs live in a dedicated `zh_hans/` folder alongside the existing `.id.md` suffix
files (which should also eventually move to `id/`).
- [x] Audit all top-level `docs/*.md` for correctness against the current
v0.9.x codebase; flag stale content, broken links, and outdated commands.
Priority: `INSTALL.md`, `GUIDE.md`, `CONFIGURATION.md`, `FLEET.md`,
`KEYBINDINGS.md`, `MODES.md`, `PROVIDERS.md`.
- [x] Move the two existing Chinese translations into `docs/zh_hans/`:
`LSP_PHP_CUSTOM.zh-CN.md` → `docs/zh_hans/LSP_PHP_CUSTOM.md`
`WINDOWS_BEGINNER.zh-CN.md` → `docs/zh_hans/WINDOWS_BEGINNER.md`
Keep the original `.zh-CN.md` files as symlinks or redirect stubs for one
release cycle, then remove.
- [x] Add a `docs/zh_hans/README.md` (简体中文阅读指南) — a guided reading index
for Chinese users, ordered by experience level:
1. 零基础 (absolute beginner): `WINDOWS_BEGINNER.md`, `HarmonyOS.md`, `INSTALL.md`
2. 入门用户 (getting started): `GUIDE.md`, `KEYBINDINGS.md`, `MODES.md`, `PROVIDERS.md`
3. 进阶用户 (power user): `CONFIGURATION.md`, `FLEET.md`, `MCP.md`, `HOOKS.md`, `SUBAGENTS.md`, `TOOL_SURFACE.md`, `AGENT_RUNTIME.md`
4. 开发者 (developer): `ARCHITECTURE.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `RUNTIME_API.md`
## Tier 2 — complete Chinese localization (user-facing docs, priority order)
Translate every user-facing doc. These are the docs a Chinese user hits when
installing, configuring, or troubleshooting CodeWhale. Each translation lives
in `docs/zh_hans/.md` and keeps the English filename stem so the mapping
is obvious.
### Must-have (blocking for a "complete" Chinese docs experience)
- [x] `INSTALL.md` → `docs/zh_hans/INSTALL.md` (39 KB — every user's first stop)
- [x] `GUIDE.md` → `docs/zh_hans/GUIDE.md` (27 KB — first-hour walkthrough)
- [x] `CONFIGURATION.md` → `docs/zh_hans/CONFIGURATION.md` (154 KB — largest doc;
can ship in sections: core config first, advanced options later)
- [x] `KEYBINDINGS.md` → `docs/zh_hans/KEYBINDINGS.md` (19 KB)
- [x] `FLEET.md` → `docs/zh_hans/FLEET.md` (38 KB)
- [x] `MODES.md` → `docs/zh_hans/MODES.md` (21 KB)
- [x] `MCP.md` → `docs/zh_hans/MCP.md` (17 KB)
- [x] `PROVIDERS.md` → `docs/zh_hans/PROVIDERS.md` (91 KB — Chinese users
especially need this for domestic model providers)
- [x] `HOOKS.md` → `docs/zh_hans/HOOKS.md` (29 KB)
- [x] `SUBAGENTS.md` → `docs/zh_hans/SUBAGENTS.md` (35 KB)
- [x] `SKILLS.md` → `docs/zh_hans/SKILLS.md` (15 KB)
- [x] `AGENT_RUNTIME.md` → `docs/zh_hans/AGENT_RUNTIME.md` (17 KB)
- [x] `TELEMETRY.md` → `docs/zh_hans/TELEMETRY.md` (29 KB)
- [x] `TOOL_LIFECYCLE.md` → `docs/zh_hans/TOOL_LIFECYCLE.md` (26 KB)
### Should-have (important but can follow the must-have wave)
- [ ] `PLUGINS.md` → `docs/zh_hans/PLUGINS.md` (4.5 KB)
- [ ] `PLUGIN_BUNDLES.md` → `docs/zh_hans/PLUGIN_BUNDLES.md` (19 KB)
- [ ] `MEMORY.md` → `docs/zh_hans/MEMORY.md` (8 KB)
- [ ] `SANDBOX.md` → `docs/zh_hans/SANDBOX.md` (9 KB)
- [ ] `WEB.md` → `docs/zh_hans/WEB.md` (3.7 KB)
- [ ] `WORKFLOW_AUTHORING.md` → `docs/zh_hans/WORKFLOW_AUTHORING.md` (7.7 KB)
- [ ] `FLEET_WORKFLOW_TUTORIAL.md` → `docs/zh_hans/FLEET_WORKFLOW_TUTORIAL.md` (10.8 KB)
- [ ] `DOCKER.md` → `docs/zh_hans/DOCKER.md` (10.5 KB)
- [ ] `TERMUX.md` → `docs/zh_hans/TERMUX.md` (5.4 KB)
- [ ] `ACCESSIBILITY.md` → `docs/zh_hans/ACCESSIBILITY.md` (6.8 KB)
- [ ] `CACHE.md` → `docs/zh_hans/CACHE.md` (5.7 KB)
- [ ] `CATALOG_REFRESH.md` → `docs/zh_hans/CATALOG_REFRESH.md` (10 KB)
- [ ] `BUILD_PERFORMANCE.md` → `docs/zh_hans/BUILD_PERFORMANCE.md` (24 KB)
- [ ] `VOICE.md` → `docs/zh_hans/VOICE.md` (2.5 KB)
- [ ] `LOCALIZATION.md` → `docs/zh_hans/LOCALIZATION.md` (17 KB)
- [ ] `REBRAND.md` → `docs/zh_hans/REBRAND.md` (11 KB)
- [ ] `HarmonyOS.md` → `docs/zh_hans/HarmonyOS.md` (5.5 KB — especially relevant
for Chinese users on Huawei devices)
- [ ] `CNB_MIRROR.md` → `docs/zh_hans/CNB_MIRROR.md` (8.7 KB — especially
relevant for Chinese users behind the GFW)
## Tier 3 — developer and internal docs (nice-to-have, lower priority)
These docs are primarily for contributors and power users. Translate them when
Tier 2 is complete and there is community demand.
- [ ] `ARCHITECTURE.md` → `docs/zh_hans/ARCHITECTURE.md` (21.5 KB)
- [ ] `AGENT_ETHOS.md` → `docs/zh_hans/AGENT_ETHOS.md` (3 KB)
- [ ] `AUTHORIZATION_ORDER.md` → `docs/zh_hans/AUTHORIZATION_ORDER.md` (9 KB)
- [ ] `AUTOMATIC_WORKFLOWS.md` → `docs/zh_hans/AUTOMATIC_WORKFLOWS.md` (7 KB)
- [ ] `COMMAND_CONTROL_PLANE.md` → `docs/zh_hans/COMMAND_CONTROL_PLANE.md` (7 KB)
- [ ] `ENVIRONMENTS.md` → `docs/zh_hans/ENVIRONMENTS.md` (2 KB)
- [ ] `LEGACY_PATHS.md` → `docs/zh_hans/LEGACY_PATHS.md` (3 KB)
- [ ] `LIVE_SMOKE.md` → `docs/zh_hans/LIVE_SMOKE.md` (8 KB)
- [ ] `OPERATIONS_RUNBOOK.md` → `docs/zh_hans/OPERATIONS_RUNBOOK.md` (3.7 KB)
- [ ] `RUNTIME_API.md` → `docs/zh_hans/RUNTIME_API.md` (53 KB)
- [ ] `TOOL_SURFACE.md` → `docs/zh_hans/TOOL_SURFACE.md` (14 KB)
- [ ] `WORKROOM_ARCHITECTURE.md` → `docs/zh_hans/WORKROOM_ARCHITECTURE.md` (5 KB)
- [ ] `WORKROOM_SECURITY.md` → `docs/zh_hans/WORKROOM_SECURITY.md` (4 KB)
## Out of scope (not suitable for translation)
- `docs/rfcs/*` — internal design RFCs; change frequently, audience is
contributors who read English
- `docs/design/*` — design notes; same reasoning
- `docs/architecture/*` — architecture notes; same reasoning
- `docs/decisions/*` — decision records; same reasoning
- `docs/skills/*` — skill definitions already include English identifiers
- `docs/schemas/*` — machine-readable schemas
- `docs/examples/*` — code/config examples; code stays English
- `docs/images/*` — binary assets
- `docs/releases/*` — release notes
- `CHANGELOG_ARCHIVE.md` — 276 KB historical archive; not worth translating
- `CONTRIBUTORS.md` — 57 KB contributor list; auto-generated
- `ACP_REGISTRY_SUBMISSION.md`, `CLAUDE_PLUGIN_COMPAT.md`, `ISSUE_TRIAGE.md`,
`MOTION_CONTRACT.md`, `POST_0_9_1_SEAMS.md`, `PREVIEW_REQUEST.md`,
`RECEIPTS.md`, `RELEASE_CHECKLIST.md`, `RELEASE_RUNBOOK.md`,
`SETTINGS_PICKER_FRAMEWORK.md`, `WORKFLOW_EXPERIMENTAL_SEARCH.md`,
`CLASSROOM_INSTALL.md`, `INTEGRATIONS_DSH.md`, `MODEL_LAB.md` —
internal process docs; English-only is fine
## Mechanism
- Each translated doc lives at `docs/zh_hans/.md` with the same filename
stem as the English source.
- `docs/zh_hans/README.md` is the canonical Chinese reading index.
- English docs link to their Chinese counterparts with a language switcher
banner at the top (e.g. `> 阅读简体中文版:[zh_hans/INSTALL.md]`).
- Chinese docs include a back-link to the English source and a "last synced
with English revision" date so staleness is visible.
- `LOCALIZATION.md` gains a "Docs translations" table tracking per-doc status
(shipped / partial / planned / deferred).
Contributor guide
Research direction
Start by reading the localization mechanism and the planned entries for docs/zh_hans/README.md and LOCALIZATION.md, then compare the listed English docs with their translation status. Work through the remaining Tier 2 and Tier 3 documents in priority order. Done means translations, source links, language-switcher banners, sync dates, and the tracking table are complete.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, localization
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100