160 lines
3.7 KiB
Markdown
160 lines
3.7 KiB
Markdown
# 国际化指南（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`。
|