# 国际化指南（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`。