docs: reorganize docs into guide/ and electron/, add 6 new guide docs, update README

2026-06-10 17:01:48 +08:00
parent 99f80147c7
commit 686b1b45ea
11 changed files with 950 additions and 75 deletions
--- a/docs/guide/I18N.md
+++ b/docs/guide/I18N.md
@@ -0,0 +1,159 @@
+# 国际化指南（i18n）
+
+## 双源体系
+
+| 类别 | 位置 | 加载 | 维护者 |
+|------|------|------|--------|
+| **UI 文案**（按钮、菜单、设置） | `src/locales/{zh,en,ja}.json` | `import` 打包进 bundle | 引擎开发者 |
+| **故事文案**（选项、提示、章节名） | `public/demo/locales/{zh,en,ja}.json` | `fetch()` 动态加载 | 故事创作者 |
+
+**核心理念：** 游戏制作者只需编辑 `public/` 下的 JSON，刷新页面即生效，不需要重新打包。
+
+## 数据层 i18n（故事文案）
+
+### 架构
+
+```json
+// public/scenes/demo.json
+{
+  "locales": { "path": "locales/", "languages": ["zh", "en", "ja"] },
+  "scenes": {
+    "intro": {
+      "choices": [
+        { "text": "走向左边那扇发光的门", "textKey": "intro.choice.left_door", ... }
+      ]
+    }
+  }
+}
+```
+
+```json
+// public/demo/locales/zh.json
+{
+  "intro": {
+    "choice": {
+      "left_door": "走向左边那扇发光的门"
+    }
+  }
+}
+```
+
+```json
+// public/demo/locales/en.json
+{
+  "intro": {
+    "choice": {
+      "left_door": "Walk toward the glowing door on the left"
+    }
+  }
+}
+```
+
+### 所有支持 i18n 的数据字段
+
+| 数据对象 | 字段 | key 字段 | 示例 key |
+|---------|------|---------|----------|
+| Choice | `text` | `textKey` | `"intro.choice.left_door"` |
+| Choice | `prompt` | `promptKey` | `"left_door.prompt.handshake"` |
+| QTE | `prompt` | `promptKey` | `"right_door.qte.dodge"` |
+| Hotspot | `label` | `labelKey` | `"investigation_site.hotspot.desk"` |
+| Chapter | `label` | `labelKey` | `"chapter.ch1"` |
+| Ending | `label` | `labelKey` | `"ending.trust_end"` |
+| Achievement | `title` | `titleKey` | `"achievement.qte_master.title"` |
+| Achievement | `description` | `descKey` | `"achievement.qte_master.desc"` |
+
+**规律：** 每个可国际化的数据字段都有对应的 `xxxKey` 版本。引擎先查 key，找不到时回退原始字段值。
+
+### 回退逻辑
+
+```
+t('intro.choice.left_door')
+  → 查 public/locales/{lang}.json
+  → 找到了 → 返回翻译文本
+  → 找不到 → 返回 choice.text（"走向左边那扇发光的门"）
+```
+
+### Locale JSON 结构示例
+
+```json
+{
+  "intro": {
+    "choice": {
+      "left_door": "...",
+      "right_door": "...",
+      "search": "...",
+      "stay": "..."
+    }
+  },
+  "left_door": {
+    "choice": {
+      "handshake": "...",
+      "reject": "..."
+    },
+    "prompt": {
+      "handshake": "..."
+    }
+  },
+  "right_door": {
+    "qte": { "dodge": "..." }
+  },
+  "chapter": {
+    "ch1": "第一章：醒来",
+    "ch2": "第二章：调查"
+  },
+  "ending": {
+    "trust_end": "信任的伙伴",
+    "alone_end": "独行之路"
+  },
+  "achievement": {
+    "qte_master": {
+      "title": "反应达人",
+      "desc": "成功完成一次 QTE"
+    }
+  }
+}
+```
+
+## 新增语言的方法
+
+### 1. 注册到引擎
+
+`src/locales/` 新增语言文件（复制 `en.json` 翻译）：
+
+```bash
+cp src/locales/en.json src/locales/ko.json
+# 编辑 src/locales/ko.json → 翻译 UI 文案
+# 编辑 src/composables/useI18n.ts → 新增 `import ko from '@/locales/ko.json'` + 加入 `uiMessages`
+```
+
+### 2. 注册到故事数据
+
+`public/demo/locales/` 新增语言文件：
+
+```bash
+cp public/demo/locales/en.json public/demo/locales/ko.json
+# 编辑 → 翻译故事文案
+```
+
+`demo.json` 的 `locales.languages` 数组加 `"ko"`：
+
+```json
+"locales": { "path": "locales/", "languages": ["zh", "en", "ja", "ko"] }
+```
+
+### 3. 刷新页面
+
+语言切换按钮自动新增韩语选项，无需重新构建。
+
+## 配置语言目录
+
+所有 locale 文件放在 `assetBase` 指定的基础路径下。JSON 中配置：
+
+```json
+{
+  "assetBase": "my_story/",
+  "locales": { "path": "lang/", "languages": ["zh", "en"] }
+}
+```
+
+则语言文件路径为 `my_story/lang/zh.json`。