| name | docs-i18n |
| description | Sync GenUI SDK docs between Chinese and English when adding, editing, renaming, or deleting documentation under docs/. Use when the user modifies docs/src/, docs/demos/, docs/demos/en/, zh-theme.ts, en-theme.ts, or asks to update English docs, i18n docs, or mirror Chinese documentation changes. |
GenUI SDK 文档国际化
完整约定见仓库根目录 docs/I18N.md。修改中文文档时（共享 demo、仅改图片等例外除外），必须同步英文镜像与导航配置。
目录映射
| 类型 | 中文 | 英文 |
|---|
| Markdown | docs/src/<path>.md | docs/src/en/<path>.md |
| Demo | docs/demos/<path>.vue | docs/demos/en/<path>.vue |
| 图片 | docs/src/public/（共用，无需复制） | 同上 |
| 中文导航 | docs/.vitepress/config/zh-theme.ts | — |
| 英文导航 | — | docs/.vitepress/config/en-theme.ts |
路径规则：
- 文档：
docs/src/examples/chat/foo.md → docs/src/en/examples/chat/foo.md（在 src/ 后插入 en/）
- Demo：
docs/demos/chat/foo.vue → docs/demos/en/chat/foo.vue（在 demos/ 后插入 en/，文件名相同）
工作流程
根据用户操作选择对应流程，完成后执行「验证清单」。
新增文档
- 编写中文
docs/src/<path>.md
- 有交互示例时：
- 中文：
docs/demos/<name>.vue
- 含中文 UI/文案时：
docs/demos/en/<name>.vue（翻译 UI 文案、alert、Schema label 等；代码注释可翻译或保留）
- 纯英文、无文本、或 i18n 演示类 demo → 共用中文版，不建
demos/en/ 镜像
- 图片放入
docs/src/public/（中英文共用）
- 在
zh-theme.ts 对应 sidebar 添加条目：
{ text: '中文标题', link: '/examples/chat/my-feature' },
- 创建并翻译
docs/src/en/<path>.md
- 在
en-theme.ts 对应 sidebar 添加条目（链接带 /en 前缀）：
{ text: 'English Title', link: '/en/examples/chat/my-feature' },
- 本地预览：
cd docs && pnpm dev
修改文档
| 变更类型 | 同步动作 |
|---|
| 改正文 / 标题 / 代码块 | 更新 docs/src/en/ 下对应文件（翻译变更部分） |
| 改 demo 引用或逻辑 | 同步 docs/demos/ 与 docs/demos/en/ 中对应 .vue（如有） |
| 改 sidebar 文案或顺序 | 同步更新 zh-theme.ts 与 en-theme.ts 对应条目 |
| 仅改图片 | 无需动英文 md（public 共用） |
重命名 / 移动
- 移动中文 md → 同步移动
docs/src/en/ 下镜像文件
- 移动 demo → 同步移动
docs/demos/en/ 下镜像文件（如存在）
- 更新
zh-theme.ts 与 en-theme.ts 中所有相关 link
- 检查文档内相对路径引用是否仍有效
删除文档
- 删除
docs/src/<path>.md
- 删除
docs/src/en/<path>.md
- 删除关联 demo（
docs/demos/ 与 docs/demos/en/ 下对应文件）
- 从
zh-theme.ts 与 en-theme.ts 移除对应 sidebar 条目
英文文档编写规则
路径调整（从中文复制时必改）
英文 md 比中文多一层 en/，<demo> 与图片的相对路径需多加一层 ../，并将 demo 路径指向 demos/en/：
<!-- 中文 docs/src/examples/chat/foo.md -->
<demo vue="../../../demos/chat/foo.vue" />
<!-- 英文 docs/src/en/examples/chat/foo.md -->
<demo vue="../../../../demos/en/chat/foo.vue" />
- 文档内互相引用：相对路径写法与中文相同
- sidebar / nav 的
link：英文必须带 /en 前缀（如 /en/guide/quick-start）
翻译原则
- 翻译自然、技术准确的英文，勿逐字机翻
- 保留 API 名称、组件名、包名、文件名、路径（如
@opentiny/genui-sdk-vue、GenuiChat）
- 代码块：仅翻译注释与字符串字面量；结构、导入、类型与中文一致
- 标题层级、章节顺序、代码块行高亮（如
{12-19}）与中文版对齐
Demo 需翻译的内容
| 类型 | 示例 | 处理 |
|---|
| UI 文案 | <button>新建会话</button> | 译成英文 |
| 代码注释 | // 获取会话对象 | 翻译或保留 |
| Schema 内容 | label: '姓名' | 译成英文 |
| alert 消息 | alert('复制成功') | 译成英文 |
无需国际化的 Demo
以下 demo 无需创建 demos/en/ 镜像，直接共用中文版：
- 纯英文内容的 demo
- 国际化示例 demo（如
i18n.vue，本身演示 i18n 功能）
- 无文本内容的 demo
导航配置对照
两个 theme 文件结构镜像，修改时成对维护：
zh-theme.ts：nav / sidebar 的 link 无 /en 前缀en-theme.ts：相同路径结构，link 以 /en 开头；text 为英文
sidebar 按路径前缀分组（/guide/、/components/、/examples/、/schema/、/advanced/），新增条目放入与中文版相同的分组与层级。
验证清单
完成同步后逐项确认：
- [ ] docs/src/en/ 下存在对应的翻译文件，路径正确
- [ ] zh-theme.ts 与 en-theme.ts 均有对应 sidebar 条目且 link 正确
- [ ] zh-theme.ts 与 en-theme.ts 顶层 nav 映射一致，英文 link 带 /en 前缀
- [ ] 英文 md 中 <demo> 路径多一层 ../，且指向 demos/en/ 下对应文件（如需）
- [ ] demo 含中文内容时已在 docs/demos/en/ 提供镜像
- [ ] 删除场景下无残留英文文件、demo、sidebar 条目
- [ ] 可选：cd docs && pnpm dev 本地预览中英文页面
快速定位镜像文件
中文：docs/src/examples/chat/history.md
英文：docs/src/en/examples/chat/history.md
中文 demo：docs/demos/chat/history.vue
英文 demo：docs/demos/en/chat/history.vue
