feat(docs): add bilingual package documentation site

2026-09-20 15:53:28 +08:00
parent 60f6f1fb1a
commit dc80bd8ae0
111 changed files with 6531 additions and 0 deletions
@@ -0,0 +1,33 @@
+---
+title: 生产环境词典
+description: 理解词典合并、紧凑消息键、资源生成和 SSR 行为。
+order: 20
+toc:
+  - id: merge-order
+    title: 合并顺序
+  - id: build-output
+    title: 构建产物
+  - id: server-rendering
+    title: 服务端渲染
+---
+
+## 合并顺序 {#merge-order}
+
+包词典按配置顺序合并，应用词典最后合并。因此应用默认只需翻译自身消息，除非它有意自定义包内文案。
+
+> 只导入应用实际使用的词典来源。特定 Block 的入口不会导入无关功能的词典。
+
+## 构建产物 {#build-output}
+
+生产构建期间，插件会：
+
+1. 为每种语言合并配置的词典；
+2. 根据语义消息 ID 创建共享 Schema；
+3. 将这些 ID 替换为确定的紧凑键；
+4. 为每种语言输出一个带内容哈希的 JSON 资源。
+
+私有 Schema 仅用于构建诊断，不会发送到浏览器。
+
+## 服务端渲染 {#server-rendering}
+
+SSR Bundle 会嵌入匹配的紧凑词典。浏览器导航只加载选中语言的资源，因此增加语言不会让主应用 Bundle 重复包含所有翻译。
@@ -0,0 +1,44 @@
+---
+title: CLI 与 Message Studio
+description: 添加语言、提取消息、编译词典并运行翻译界面。
+order: 21
+toc:
+  - id: scripts
+    title: Scripts
+  - id: commands
+    title: 命令
+  - id: daily-workflow
+    title: 日常工作流
+---
+
+## Scripts {#scripts}
+
+```json
+{
+  "scripts": {
+    "i18n": "workspace-i18n",
+    "i18n:extract": "workspace-i18n extract",
+    "i18n:compile": "workspace-i18n compile",
+    "i18n:ui": "workspace-i18n ui"
+  }
+}
+```
+
+## 命令 {#commands}
+
+- `new <locale>` 校验 BCP 47 标签、更新配置并创建词典。
+- `extract` 查找应用消息并更新词典。
+- `compile` 生成 TypeScript 词典模块。
+- `ui` 启动带有 Extract 和 Compile 操作的 Message Studio。
+
+在应用目录外执行时，每个命令都接受 `--project <path>`。
+
+## 日常工作流 {#daily-workflow}
+
+```sh
+bun run i18n extract
+bun run i18n ui
+bun run i18n compile
+```
+
+提交应用配置以及 `en-US`、`zh-Hans` 词典。生成的私有 Schema 数据仍属于构建产物。