国际化指南（i18n）

双源体系

类别	位置	加载	维护者
UI 文案（按钮、菜单、设置）	`src/locales/{zh,en,ja}.json`	`import` 打包进 bundle	引擎开发者
故事文案（选项、提示、章节名）	`public/demo/locales/{zh,en,ja}.json`	`fetch()` 动态加载	故事创作者

核心理念： 游戏制作者只需编辑 public/ 下的 JSON，刷新页面即生效，不需要重新打包。

数据层 i18n（故事文案）

架构

// public/scenes/demo.json
{
  "locales": { "path": "locales/", "languages": ["zh", "en", "ja"] },
  "scenes": {
    "intro": {
      "choices": [
        { "text": "走向左边那扇发光的门", "textKey": "intro.choice.left_door", ... }
      ]
    }
  }
}

// public/demo/locales/zh.json
{
  "intro": {
    "choice": {
      "left_door": "走向左边那扇发光的门"
    }
  }
}

// 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 结构示例

{
  "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 翻译）：

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/ 新增语言文件：

cp public/demo/locales/en.json public/demo/locales/ko.json
# 编辑 → 翻译故事文案

demo.json 的 locales.languages 数组加 "ko"：

"locales": { "path": "locales/", "languages": ["zh", "en", "ja", "ko"] }

3. 刷新页面

语言切换按钮自动新增韩语选项，无需重新构建。

配置语言目录

所有 locale 文件放在 assetBase 指定的基础路径下。JSON 中配置：

{
  "assetBase": "my_story/",
  "locales": { "path": "lang/", "languages": ["zh", "en"] }
}

则语言文件路径为 my_story/lang/zh.json。

3.7 KiB Raw Blame History Unescape Escape