8.8 KiB
TH1 创意工坊多语言 Mod 设计与工作流文档
1. 核心设计原则与边界
基于 TH1 现有的多语言系统架构，本创意工坊方案的设计核心为**“现有语种的局部文本替换”**。为了保证系统的稳定性和玩家创作的低门槛，明确以下设计边界：
- 仅替换，不新增：多语言 Mod 仅用于修改和润色游戏中已存在的语言（如 ZH, EN, JP 等），不支持通过 Mod 新增全新的语言枚举。但系统提供了一个特殊的 Custom（自定义）语种，专供 Mod 应用时使用——它不参与游戏本体的多语言流程，只作为 Mod 目标语言的一个额外选项。
- 无需处理字体：因为不新增语种，所有 Mod 的显示将直接复用游戏本体中该语言对应的原有字体（TMP_FontAsset）以及排版配置，创作者完全不需要考虑字体渲染和缺失问题。Custom 语种回退到 EN 字体。
- 支持增量/部分替换：Mod 允许只修改一部分文本。玩家不需要翻译游戏内的所有内容，翻译了哪几条，游戏运行时就仅替换那几条，未修改的内容保持游戏默认文本。
- 多 Mod 优先级处理：玩家可以为每个语种单独配置一组 Mod 列表及其优先级。低优先级 Mod 先应用，高优先级 Mod 后应用（覆盖低优先级）。Mod 本身不绑定语种——任意 Mod 可以被分配给任意语种。此配置存储在
GameConfig.ModLanguageConfigs中，由 UI 或编辑器面板负责设置。 - Mod 与语种解耦：导出模板时，玩家可以分别指定"目标语种"（Mod 最终要修改的语种）和"参考语种"（CSV 中显示的参照文本列）。mod_info 记录创作者声明的目标语种，但在应用阶段可以被玩家的优先级配置覆盖。
2. 玩家共创工作流（Modder 视角）
对于想要参与多语言优化的创作者，整体流程分为三个简单的步骤，所有操作均设计为“零门槛”。
步骤一：一键获取 Mod 源文件
玩家无需寻找游戏目录或解包游戏，在游戏客户端内点击**"获取翻译模板"按钮，并指定目标语种**（要修改的语言）和参考语种（CSV 中显示的参照列）。 系统会自动在本地生成标准化的 Mod 源文件文件夹，包含所有可翻译内容的对照表及 Mod 配置文件。
步骤二：本地编辑翻译内容
玩家打开生成的本地文件夹，找到对应的翻译表格文件（CSV 格式）。 表格共 4 列：
- ID：游戏内多语言系统分配的唯一标识符（不可修改）。
- EN：英文文本，作为翻译标准参考。
- {参考语种}：玩家指定的参考语言列，供对照（修改无效）。
- Translation：创作者填写的翻译内容。只有此列有内容的行才会在游戏中生效替换；留空则保持原文。
玩家只需使用 Excel 或任意文本编辑器，将润色后的文本填入 Translation 列即可。
步骤三：上传至创意工坊
玩家完成本地编辑，并在文件夹内准备好一张预览图（封面图）后，回到游戏客户端中。 点击**"上传 Mod"按钮，在游戏内 UI 中选择刚刚编辑好的文件夹，填写好 Mod 的名称和简介，即可一键打包并上传到 Steam 创意工坊，供其他玩家订阅。“主菜单”或“Mod 菜单”中）点击“获取翻译模板”**按钮。
步骤三：上传至创意工坊
表格中会清晰地列出每条文本的**“唯一 ID”、“原文参考”以及留空的“翻译内容列”**。 玩家只需要使用 Excel 或任意文本编辑器，将自己润色或修改后的文本填入“翻译内容列”即可。不想修改的条目直接留空，系统会自动忽略。
步骤三：上传至创意工坊
玩家完成本地编辑，并在文件夹内准备好一张预览图（封面图）后，回到游戏客户端中。 点击**“上传 Mod”**按钮，在游戏内 UI 中选择刚刚编辑好的文件夹，填写好 Mod 的名称和简介，即可一键打包并上传到 Steam 创意工坊，供其他玩家订阅。
3. 玩家使用工作流（订阅者视角）
对于普通的玩家，体验多语言 Mod 的流程完全无感化：
- 订阅 Mod：玩家在 Steam 社区的 TH1 创意工坊页面浏览，点击“订阅”心仪的翻译优化 Mod。
- 自动生效：Steam 客户端会自动下载文件。玩家启动游戏后，无需任何额外配置，游戏内对应语言的文本就已经被自动替换为 Mod 中的版本。
4. Mod 文件结构与数据定义
一个标准的多语言 Mod 文件夹在本地包含以下三个核心文件：
-
mod_info 配置 用于声明该 Mod 的基础元数据，主要包括：Mod 的标题、作者，以及该 Mod 创作者声明的目标替换语种（如 EN、ZH、Custom 等）。注意：在应用阶段，玩家可通过优先级配置将任意 Mod 用于任意语种，覆盖此声明。
-
translation 翻译数据表（CSV 格式，4 列） 这是 Mod 的核心数据载体。表结构如下：
列名 说明 ID 游戏内唯一标识符（不可修改） EN 英文原文，作为翻译标准参考（修改无效） {参考语种} 玩家导出时指定的参考语言原文（修改无效） Translation 创作者填写的翻译内容。非空才生效，空则跳过 示例（目标 ZH，参考 EN）：
ID,EN,EN,Translation item_sword_name,Iron Sword,Iron Sword,铁剑 item_shield_name,Wooden Shield,Wooden Shield, -
preview 封面图 一张用于展示在 Steam 创意工坊列表中的预览图片。
5. 运行时读取与覆盖流程
游戏启动
↓
MultilingualManager.Init()
→ 加载官方多语言数据（Resources/Export/Multilingual）
↓
ApplyWorkshopMods()
→ 读取 GameConfig.ModLanguageConfigs（玩家的语种-Mod 优先级配置）
↓
WorkshopModLoader.ApplyModsWithConfig(data, configs)
对每个语种配置：
按列表顺序（低→高优先级）依次应用各 Mod：
读取 mod_info.json → 确定目标语种（优先使用配置覆盖，其次用 mod_info 声明）
读取 translation.csv → 仅处理 Translation 列非空的行
在内存中覆盖对应 ID 的目标语种字段
↓
ChangedMultilingual(currentType) → 刷新所有 UI 文本
关于嵌套引用的兼容性：“翻译内容”不为空，则在内存中找到对应 ID 的多语言数据节点。
关于嵌套引用的兼容性：
原系统的 **<id>** 专有名词嵌套引用机制与 Mod 系统完全兼容。只要玩家在 Translation 列保留了 **<id>** 格式，运行时底层仍会正常触发解析，无需任何特殊处理。
6. Workshop 浏览器（编辑器功能）
由于游戏未正式发售导致创意工坊页面无法直接在 Steam 客户端访问，编辑器内提供了 Workshop 浏览器标签页（⑤ 工坊浏览）：
- 查询：分页查询当前 AppId 对应创意工坊中的所有 Mod（通过
SteamUGC.CreateQueryAllUGCRequest）。 - 订阅/取消订阅：直接在编辑器内操作，Steam 客户端自动处理下载/删除。
- 状态显示：显示每个 Mod 的订阅状态、安装状态、本地路径、标签、投票数等信息。
- 驱动机制：编辑器通过
EditorApplication.update定期调用SteamAPI.RunCallbacks()驱动 Steamworks 异步回调，无需运行游戏。
核心类：Logic.Multilingual.WorkshopModBrowser（单例）
7. 编辑器测试面板（WorkshopModEditorWindow）
菜单路径：TH1工具 → 创意工坊多语言 Mod 测试面板
| 标签页 | 功能说明 |
|---|---|
| ① 导出模板 | 指定目标语言 + 参考语言，导出 4 列 CSV 模板（Translation 列留空） |
| ② 上传Workshop | 选择 Mod 文件夹上传到 Steam 创意工坊 |
| ③ Mod优先级 | 模拟为每个语种分配 Mod 并调整优先级（▲▼排序、添加/移除） |
| ④ 应用Mod | 按优先级配置或批量应用本地/订阅 Mod，支持目标语言覆盖 |
| ⑤ 工坊浏览 | 查询当前 AppId 所有 Workshop Mod，支持订阅/取消订阅 |
| ⑥ CSV测试 | 4 列 CSV 读写回环测试（含特殊字符验证） |
| ⑦ 数据检视 | 查看多语言数据概览、按 ID 查询、检视 Mod 文件夹内容（4 列格式） |