dingyuntian
7d7c8893fc
- 新增 Editor 窗口：AIBIS → Yarn 本地化校验 - 新增 BatchMode CLI：Tools/validate_yarn_l10n.py - 新增文档：Docs/本地化校验工具.md - 校验 Yarn 原文 string table 与各语言 CSV 的 line id 一致性
95 lines
3.1 KiB
Markdown
95 lines
3.1 KiB
Markdown
# Yarn 本地化校验工具
|
||
|
||
校验 Yarn 章节文件夹内 **原文（编译器 string table）** 与各语言翻译 CSV 的 line id 是否一致。
|
||
|
||
## 背景
|
||
|
||
典型 Yarn 章节文件夹结构：
|
||
|
||
```
|
||
{章节名}/
|
||
├── {章节名}.yarnproject
|
||
├── {脚本}.yarn ← 中文原文 + #line:xxxxxxx
|
||
├── {章节名}-en.csv ← 英语
|
||
└── {章节名}-ja.csv ← 日语（注意：实际文件名为 -ja，不是 -jp）
|
||
```
|
||
|
||
编剧修改 `.yarn` 后，翻译 CSV 容易不同步。本工具报告：
|
||
|
||
- **缺少本地化-{语言}**：原文 id 存在，CSV 中没有
|
||
- **找不到原文-{语言}**：CSV 中有 id，原文已不存在
|
||
- **原文已变更-{语言}**（可选）：Lock 不一致，翻译可能过期
|
||
|
||
原文 id 来自 **Yarn Spinner 编译器**（与 Inspector「Export Strings and Metadata as CSV」同源），不是手工正则扫 `.yarn`。
|
||
|
||
参考样例：`Assets/Yarn/FP/FP_Day1_mid`
|
||
|
||
## Unity Editor 窗口
|
||
|
||
菜单：**AIBIS → Yarn 本地化校验**
|
||
|
||
1. 选择章节文件夹（如 `Assets/Yarn/FP/FP_Day1_mid`）
|
||
2. 点击 **校验**
|
||
3. 可选 **导出 CSV** 报告
|
||
4. 勾选 **扫描子目录** 可批量校验 `Assets/Yarn/` 下所有 `.yarnproject`
|
||
|
||
## 命令行 / CI
|
||
|
||
Python 脚本 **不独立实现校验**，通过 Unity BatchMode 调用同一套 Editor 逻辑。
|
||
|
||
```bash
|
||
# 校验单个章节
|
||
python Tools/validate_yarn_l10n.py Assets/Yarn/FP/FP_Day1_mid
|
||
|
||
# 扫描 Assets/Yarn 下所有章节
|
||
python Tools/validate_yarn_l10n.py Assets/Yarn --scan-all
|
||
|
||
# 导出 CSV
|
||
python Tools/validate_yarn_l10n.py Assets/Yarn/FP/FP_Day1_mid --export report.csv
|
||
|
||
# CI：存在 blocking issue 时非零退出
|
||
python Tools/validate_yarn_l10n.py Assets/Yarn --scan-all --fail-on-issues
|
||
```
|
||
|
||
**环境要求**
|
||
|
||
- Unity 2022.3.7f1c1（或设置环境变量 `UNITY_EDITOR_PATH` 指向 `Unity.exe`）
|
||
- 首次 BatchMode 可能较慢（导入/编译）
|
||
- JSON 结果写入 `Build/yarn_l10n_result.json`，日志在 `Build/yarn_l10n_validate.log`
|
||
|
||
**直接调用 Unity（可选）**
|
||
|
||
```bash
|
||
"C:\Program Files\Unity\Hub\Editor\2022.3.7f1c1\Editor\Unity.exe" ^
|
||
-batchmode -nographics -quit ^
|
||
-projectPath "D:\UnityProject\aibis-dream" ^
|
||
-executeMethod AibisDream.YarnLocalizationValidation.Editor.YarnL10nValidatorCli.Run ^
|
||
-yarnL10nPath "Assets/Yarn/FP/FP_Day1_mid" ^
|
||
-yarnL10nOutput "Build/yarn_l10n_result.json" ^
|
||
-logFile "Build/yarn_l10n_validate.log"
|
||
```
|
||
|
||
扫描全部章节时追加 `-yarnL10nScanAll`。
|
||
|
||
## 实现位置
|
||
|
||
```
|
||
Assets/Editor/YarnLocalizationValidation/
|
||
├── YarnL10nIssue.cs
|
||
├── YarnL10nValidator.cs
|
||
├── YarnL10nValidatorCli.cs
|
||
├── YarnL10nValidationWindow.cs
|
||
└── YarnL10nReportExporter.cs
|
||
|
||
Tools/validate_yarn_l10n.py
|
||
```
|
||
|
||
## 与 Yarn Inspector 内置功能的区别
|
||
|
||
| 能力 | Inspector「Update Existing Strings Files」 | 本工具 |
|
||
|------|---------------------------------------------|--------|
|
||
| 检测缺少/多余 id | 有 | 有 |
|
||
| 检测 Lock 变更 | 有（并写回 CSV） | 有（只读报告） |
|
||
| 写回 CSV | **会** | **不会** |
|
||
| 批量扫描 / 统一报告 | 无 | 有 |
|