docs-i18n

# 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 添加条目： ```ts { text: '中文标题', link: '/examples/chat/my-feature' }, ``` 5. 创建并翻译 `docs/src/en/<path>.md` 6. 在 `en-theme.ts` 对应 sidebar 添加条目（链接带 `/en` 前缀）： ```ts { 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/`： ```markdown <!-- 中文 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/`），新增条目放入与中文版相同的分组与层级。 ## 验证清单 完成同步后逐项确认： ```markdown - [ ] 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 本地预览中英文页面 ``` ## 快速定位镜像文件 ```text 中文：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 ```