不能直接在main上维护多语种文档，因为各语言版本更新节奏、责任人和审核流程不一致，易导致翻译稿被覆盖且git log无法区分语言变更；推荐采用main（仅源语言骨架）+ lang/zh、lang/en、lang/fr分支结构，并用git worktree实现并行编辑与预览。
为什么不能直接在 main 上维护多语种文档？
因为不同语言版本的更新节奏、责任人、审核流程往往不一致。比如中文版刚发布 v1.2，英文版还在修订 v1.1 的 API 描述，法语版甚至没启动——如果全堆在 main 分支，每次 git push 都可能覆盖他人未合并的翻译稿，git log 里也分不清哪次提交改的是中文还是英文。
推荐分支结构：main + lang/zh + lang/en + lang/fr
这不是随意命名，而是有明确语义和操作约束的结构：
-
main只存放源语言（通常是英文）的原始文档骨架，比如docs/api.md的结构定义、字段说明模板，但不含完整翻译文本 - 每个
lang/<code>分支从main切出，只允许修改对应语言的子目录，如lang/zh只动docs/zh/下文件 - 禁止跨
lang/*分支直接合并；所有语言分支都通过main同步结构变更（例如新增一个章节），而非互相 merge - CI 脚本需校验：提交到
lang/zh时，自动检查是否修改了非docs/zh/路径下的文件，否则拒绝推送
git worktree 是管理多语种文档的实际刚需
你不可能等法语翻译完才开始审英文版——编辑、翻译、校对是并行任务。用 git checkout 切换分支会中断本地服务、重载 IDE 缓存、丢失终端状态。而 git worktree add ../docs-zh lang/zh 和 git worktree add ../docs-en lang/en 后，你可以：
- 在
../docs-zh里运行mdbook serve实时预览中文版 - 在
../docs-en里执行spellcheck docs/en/glossary.md - 两个目录共享同一份
.git数据，git fetch一次就能同步所有语言分支的更新 - 删除某个 worktree（如
git worktree remove ../docs-fr）不会影响其他分支或主仓库
容易被忽略的三个细节
多语种文档分支最难的不是建分支，而是保持一致性：
- 源文档结构变更（如重命名
docs/api.md→docs/v2/api.md）必须先合入main，再手动 cherry-pick 到各lang/*分支，不能靠 merge —— 否则会把其他语言的翻译内容一起带进来 -
.gitignore要排除生成物，但别误加docs/*/；正确写法是docs/*/build/和docs/*/node_modules/ - 翻译人员不需要懂 Git，所以提供封装脚本：比如
./scripts/pull-lang.sh zh自动拉取lang/zh并更新本地 worktree，比教他们记git worktree prune && git -C ../docs-zh pull现实得多
