# ichni Official 本地化工作流程（Unity Localization）

## 当前状态

- `LOC-001`：已完成。工作流、范围、命名规则与验收门已确定。
- `LOC-002`：代码实现已完成，等待 Unity Play Mode / Use Existing Build 手工验证。
- 后续阶段：未开始；在 `LOC-002` 验证通过前，不迁移 String Table、Prefab、场景或 I2。

## 1. 目标与边界

本流程用于将项目统一迁移到 Unity Localization，并保证首发版本完整支持下列七种语言：

| Locale Code | 语言 | 用途 |
| --- | --- | --- |
| `zh-CN` | 简体中文 | 原文与默认回退语言 |
| `en` | 英文 | 首发语言 |
| `zh-TW` | 繁体中文 | 首发语言 |
| `ja` | 日文 | 首发语言 |
| `ko` | 韩文 | 首发语言 |
| `vi-VN` | 越南文 | 首发语言 |
| `th` | 泰文 | 首发语言 |

范围包含菜单、设置、游戏内提示、结算、剧情树、Helper、Tutorial、歌曲元数据与当前 Chapter 0 的 Yarn 对话。

不在本轮范围内：配音、多语言图片资产、章节 1 的未完成剧情、CreatorStudio 的完整 UI 本地化。CreatorStudio 仅在 Theme `TextObject` 的共享数据契约受到影响时同步处理。

## 2. 不可违反的工作规则

1. **一次只执行一个阶段。** 每一阶段完成后，先进行代码构建和 Unity 手工验证，再批准下一阶段。
2. **不直接手改 Unity 自动生成的 String Table `.asset`。** 表、Locale、Addressables 关系通过 Unity Localization Editor 或专用导入工具创建和更新；CSV/XLSX 是可审阅的文本源。
3. **迁移期间不删除 I2。** 只有对应界面已切换、所有引用已扫描为零、并完成 Use Existing Build 回归后，才进入删除阶段。
4. **稳定 ID 与显示文本分离。** 解锁 Key、`SongItemData.songName`、Yarn Node 名称、Story Block ID 永远不翻译；只为玩家可见文本配置 Localization Key。
5. **动态文本不拼接。** 使用 Smart String 与命名参数，例如 `"已解锁歌曲：{song_name}"`；参数在弹窗实际显示时解析，以支持语言切换后的队列内容。
6. **每条文本必须有上下文。** 导出给翻译使用的表要包含界面位置、用途、占位符说明、最大长度或布局注意事项。
7. **字体与布局是验收项。** 虽然 TMP 通用字体已准备完成，仍必须在七种语言、PC 与移动端实机上检查字形、断行、溢出与字号。

## 3. 表结构与 Key 规范

### 3.1 目标 String Table Collections

| Collection | 内容 | 示例 Key |
| --- | --- | --- |
| `UI` | 所有静态菜单、设置、Gameplay 标签与通用按钮 | `ui_common_confirm` |
| `Message` | 解锁、确认、错误及其它运行时动态消息模板 | `system_unlock_song_content` |
| `Chapter0_Content` | Chapter 0 的歌曲显示名、章节元数据、Timeline、Helper 与教程文本 | `chapter0_song_world_for_white_lies_name` |
| `Chapter0_Lines` | Yarn Spinner 自动生成的 Chapter 0 台词与选项 | Yarn `#line` ID |

这四张表按加载生命周期划分，而不是按每一个页面拆分。`Chapter0_Lines` 规模最大，必须保持独立；其它表保持小而稳定。后续章节只新增 `ChapterN_Content` 与 `ChapterN_Lines` 两张表。

`UI.csv` 同时保留当前仍被场景或 Prefab 使用的旧 Key，直至对应页面完成迁移；旧 Key 不得在确认没有引用前从 Unity Table 或 CSV 中删除。

### 3.2 Key 命名

- 仅使用小写英文、数字和下划线。
- 格式为 `<域>_<模块>_<语义>`，不包含显示语言或版本号。
- 不把原文、屏幕坐标、Prefab 名称写入 Key。
- `*_title`、`*_content`、`*_desc` 成对出现时必须共享同一语义前缀。
- 智能字符串只允许命名参数：`{song_name}`、`{count}`、`{chapter_name}`；禁止 `{0}` 和 C# 字符串拼接。

## 4. 执行阶段与验收门

### LOC-001：基线盘点与迁移冻结（当前阶段）

**操作**

- 保存本文件，并建立文本资产、I2 引用、硬编码文本、Yarn 表和现有 Locale 的清单。
- 为每个待迁移对象标注目标 Collection、Key、上下文和责任阶段。
- 确认 `zh-CN` 作为原文、七种 Locale 作为首发范围、TMP 通用字体作为字体基线。

**不得操作**

- 不改运行时代码、Prefab、场景、String Table、I2 文件或 Addressables。

**验收**

- 清单明确列出所有 I2 依赖入口和所有已存在的 Unity Localization Collection。
- 后续阶段有明确的输入、输出、回滚边界与手工测试项。

### LOC-002：运行时本地化基础层

**操作**

- 将设置存档的语言选择从不稳定的 `languageIndex` 迁移为 `languageCode`，并保留旧索引到旧顺序的单次迁移逻辑。
- 保留现有 Unity Localization 官方 `InitializationOperation` 流程；不得重新引入自定义 Bootstrap 或被阻塞的场景预加载。
- 新增统一的异步文本解析入口，供动态 UI、Story 元数据与弹窗使用。

**验收**

- 删除 `SettingsSave` 后，系统语言和默认 `zh-CN` 均可稳定启动。
- 七个代码可从设置界面切换，切换后 `LocalizedString` 自动刷新。
- Windows/Android/iOS 的 Use Existing Build 均不出现 String Table 长时间 `0%` 加载。

### LOC-003：表与导入流水线

**操作**

- 由内容维护者在 Unity Localization Editor 中手动创建并维护四个 Collection，以及全部七个 Locale 的表。
- 代码与内容侧只维护版本控制中的 UTF-8 CSV 源表；由内容维护者将 CSV 转录到对应的 Unity Table。
- 每次转录前校验 Key、Yarn 行 ID、缺失翻译、重复 Key 与 Smart String 占位符。

**验收**

- 四张 CSV 与对应 Collection 同名，列顺序统一为七种首发 Locale。
- CSV 校验可报告缺失翻译、额外 Key、占位符不一致和重复 Key。
- `Message` 至少包含可验证的 Smart String 示例。

### LOC-004：静态 UI 与系统文本迁移

**操作**

- 分批迁移 `UI` 中的静态页面、系统按钮与 Gameplay 标签。
- 静态 TMP 文本使用 `LocalizeStringEvent` 或等价的 Unity Localization 组件；动态生成的 Button / Settings 控件改为统一解析入口。
- 迁移 Summary、Pause、确认框、设置项、选曲与章节页可见文本。

**验收**

- 每完成一个页面，I2 与 Unity Localization 不会同时驱动同一 TMP_Text。
- 七语切换后页面不出现 Key、空文本、Missing Script 或旧 I2 文本。

### LOC-005：动态消息与内容元数据迁移

**操作**

- 将 `MessageUIPage` 队列改为保存 `LocalizedString` 和命名参数，而非已解析的裸字符串。
- `unlock_song` 通过 `Chapter0_Content` 取歌曲显示名，并用 `system_unlock_song_title` / `system_unlock_song_content` 显示提示。
- 迁移歌曲、章节、角色、难度、Timeline Marker、Helper 的可见元数据。

**验收**

- 解锁消息能正确代入任意歌曲名；消息排队期间切换语言后，实际显示时使用新语言。
- ID、存档 Key、Story Block ID 和解锁行为不因翻译改变。

### LOC-006：剧情与对话迁移

**操作**

- 使用 Yarn Spinner 的 Unity Localization 导入/导出流程维护 `Chapter0_Lines`；不手写或复用错误的 `#line` ID。
- 导出当前 Chapter 0 全部台词、选项与行 ID，填入七种测试翻译。
- 将 StoryData 的标题、Marker、Helper 对话等非 Yarn 文本迁入 `Chapter0_Content`。

**验收**

- 每种语言均可打开所有已配置 TextBlock，选项、跳转、变量、回滚和历史记录正常。
- Yarn 行 ID、节点名称和命令参数没有被翻译或改写。

### LOC-007：Theme TextObject 与 CreatorStudio 契约

**操作**

- 将 Official Theme `TextObject` 的 I2 调用替换为 Unity Localization，同时保留 `isLocalized` / `content` 的序列化含义。
- 对应更新 CreatorStudio 的共享 `TextObject_BM` 读写契约，但不在 Creator 中维护第二套权威翻译表。
- 重建 Windows、Android、iOS Theme AssetBundle。

**验收**

- 旧 BM / Bundle 可安全读取；本地化文字在三个目标 Bundle 中正确显示。
- Bundle Manifest 与运行时日志均不存在 `I2.Loc` 类型引用。

### LOC-008：I2 清理

**操作**

- 先导出 I2 旧表作为只读迁移备份。
- 逐项确认所有场景、Prefab、脚本、Theme Bundle 和 Creator 共享元素已无 I2 引用。
- 删除 `Assets/I2`、根目录 I2 配置及依赖代码；将 `SimpleJSON` 用途迁至项目已有的 Newtonsoft JSON。

**验收**

- 全项目扫描 `I2.Loc`、`LocalizationManager`、`Localize` 均无业务引用。
- 打开场景无 Missing Script，三平台构建通过。

### LOC-009：七语翻译完成与发布 QA

**操作**

- 完成当前 UI、系统消息、内容元数据、Chapter 0 测试剧情的七语翻译。
- 执行占位符、字体、长度、断行、输入、回退、保存与 Addressables 回归。
- 冻结当前字符串；新文本必须走 CSV -> Review -> Import 流程。

**验收**

- 每个 Collection 在七种语言中均无缺失条目和占位符错误。
- PC、Android、iOS 依次验证默认语言、切换语言、重启持久化、剧情、解锁、选曲、结算、设置。
- 文本溢出和文化语义问题归零或有明确的发布豁免记录。

## 5. 阶段执行模板

每一阶段均按以下顺序执行：

1. 只读复查相关代码、Prefab、场景和当前 String Table。
2. 输出该阶段的精确文件清单、风险和回滚方法。
3. 只修改该阶段授权范围内的文件。
4. 执行 C# 构建与定向文本扫描。
5. 提供 Unity 手工测试清单；在用户确认通过前，不进入下一阶段。

## 6. 关键回归场景

- 首次启动、系统语言匹配、默认 `zh-CN` 回退。
- 设置页连续切换七种语言并立即关闭/重开游戏。
- Use Asset Database 与 Use Existing Build 的 Menu -> Story -> Song -> Game 全路径。
- MessageBox / SelectionBox 排队时切换语言；歌曲解锁时显示本地化歌曲名。
- Story Timeline、Helper、TextBlock、TutorialBlock、SongBlock、Dialog History、回滚 Marker。
- 结算页、暂停页、设置页、章节选择、选曲页在窄屏手机和 PC 窗口模式下的溢出检查。

## 7. 当前阶段后的下一步

LOC-001 完成后，先单独提交并评估 **LOC-002：运行时本地化基础层**。它只涉及语言存档契约、统一动态文本解析入口和初始化回归，不触碰 I2、Prefab 或现有 String Table 内容。