docs-i18n

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/，文件名相同）

工作流程

根据用户操作选择对应流程，完成后执行「验证清单」。

新增文档

1. 编写中文 docs/src/<path>.md
2. 有交互示例时：
   • 中文：docs/demos/<name>.vue
   • 含中文 UI/文案时：docs/demos/en/<name>.vue（翻译 UI 文案、alert、Schema label 等；代码注释可翻译或保留）
   • 纯英文、无文本、或 i18n 演示类 demo → 共用中文版，不建 demos/en/ 镜像
3. 图片放入 docs/src/public/（中英文共用）
4. 在 zh-theme.ts 对应 sidebar 添加条目：

   { text: '中文标题', link: '/examples/chat/my-feature' },
   

5. 创建并翻译 docs/src/en/<path>.md
6. 在 en-theme.ts 对应 sidebar 添加条目（链接带 /en 前缀）：

   { text: 'English Title', link: '/en/examples/chat/my-feature' },
   

7. 本地预览：cd docs && pnpm dev

修改文档

变更类型	同步动作
改正文 / 标题 / 代码块	更新 docs/src/en/ 下对应文件（翻译变更部分）
改 demo 引用或逻辑	同步 docs/demos/ 与 docs/demos/en/ 中对应 .vue（如有）
改 sidebar 文案或顺序	同步更新 zh-theme.ts 与 en-theme.ts 对应条目
仅改图片	无需动英文 md（public 共用）

重命名 / 移动

1. 移动中文 md → 同步移动 docs/src/en/ 下镜像文件
2. 移动 demo → 同步移动 docs/demos/en/ 下镜像文件（如存在）
3. 更新 zh-theme.ts 与 en-theme.ts 中所有相关 link
4. 检查文档内相对路径引用是否仍有效

删除文档

1. 删除 docs/src/<path>.md
2. 删除 docs/src/en/<path>.md
3. 删除关联 demo（docs/demos/ 与 docs/demos/en/ 下对应文件）
4. 从 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