# 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 | **会** | **不会** |
| 批量扫描 / 统一报告 | 无 | 有 |