Unity 汉化流水线（含自审计）

把「提取 → 风险判定 → 翻译 → 写入 → 自审计」做成可复用的四阶段流水线。
核心不是翻译本身，而是先判断哪些串不能翻——这是唯一会把游戏改崩的地方。

什么时候用它

用之前先确认三条，任一条不成立就不用往下走：

1. 文本在哪：Mono/IL2CPP 的 Unity 游戏，文本硬编码在托管程序集（*_Data/Managed/Assembly-CSharp.dll）或 resources.assets 里，没有 Localization 表、.po、.csv 之类的本地化资源。
   若有现成本地化表，直接用表，别改程序集。
2. 能拿到原始文件：改的是可执行文件，必须有一份未被修改过的原件做基线（备份目录、Steam 校验后重下的都行）。没有基线就不要做原地修改。
3. 中文能显示：项目内嵌的是动态字体（TMP 或 Legacy Font）。静态字体/图集字体的中文需要换贴图，本流水线只处理动态字体。

IL2CPP（无 Assembly-CSharp.dll，只有 GameAssembly.dll）不在支持范围，需要 Il2CppDumper + 重编译，另说。

快速开始

# 0) 建项目骨架（生成 l10n.json）
python <skill>/scripts/zhl10n.py init -C 你的项目目录

# 1) 清点全部 ldstr 站点（约 10s / 5000 条）
python <skill>/scripts/zhl10n.py extract

# 2) 看风险分级：哪些能翻、哪些只能定向翻、哪些绝对不能翻
python <skill>/scripts/zhl10n.py risk

# 3) 填 trans_map.json / site_map.json，然后写入（不改原件，输出到 out/build/）
python <skill>/scripts/zhl10n.py apply

# 4) 自审计（默认读 out/build 产物）
python <skill>/scripts/zhl10n.py audit --fail-on P1

一条龙：zhl10n.py all（extract → apply → audit）。

装依赖：pip install dnfile dncil UnityPy fonttools。只跑 audit 不装 UnityPy 也能用。

各环节职责

三层翻译表，职责各不相同：

• trans_map.json —— 全局表，按字符串替换所有出现位置。只放「翻成中文不会破坏逻辑」的串。
• site_map.json —— 定向表，键是 类型::方法，只改该处的 ldstr。给「同一个词在菜单里该翻、在输入系统里不能翻」这种情况用。
• enum_map.json —— 枚举名表，改的是 #Strings 堆里的字段名。给 ToString() 出来的枚举显示名用。

判定顺序：定向 → 全局。定向命中就不再走全局。

自审计

自审计是这套流水线的重点。它在写入之后独立读产物，不信任翻译表自己的说法。

输出

检查项（31 项，6 族）

CV 完整性——有没有漏

CS 一致性——术语对不对得上

FM 格式——拼接会不会坏

RK 风险——会不会把游戏改崩

IG 结构——文件本身是否还合法

RT 运行——游戏自己招了没

触发方式

三种，按场景选：

# 1. 写完立刻自检（开发循环里最常用）
zhl10n.py audit

# 2. 当门禁用：CI 或发布前，不达标直接非零退出
zhl10n.py audit --fail-on P0      # 只要有阻断级就失败
zhl10n.py audit --fail-on P1      # 默认严格度，发布建议用这个
zhl10n.py audit --fail-on P2      # 连提示都要清

# 3. 回归对比：这次改完比上次多了哪些问题
zhl10n.py audit --baseline

apply 结束时也会自动跑一次 audit，把结论打印出来——写入阶段不会在不知情的情况下产出坏包。

怎么用审计结果

1. 先看 P0。任何一条 P0 都不许发布，它等于「游戏可能起不来」。
2. 再看 P1。CV1 是漏译清单，FM1 是必崩清单，RT1 是已经崩了的证据。
3. P2 当核对表：CV1b 告诉你哪些是引擎硬约束而不是你漏了，CV5/CS4 是可以直接删的垃圾条目。
4. fixlist.csv 直接对着一行行改，改完重跑，直到 P0=0 且 P1=0。

配置（l10n.json）

{
  "project": "游戏名", "version": "1.0",
  "source": {
    "dll":     "…/Managed/Assembly-CSharp.dll",   // 只用于定位，extract 会读 backup
    "backup":  "…/_Backup/Assembly-CSharp.dll",   // 必须是未修改的原件
    "assets":  ["…/resources.assets"],
    "logs":    ["…/Player.log"]                    // 可选，供 RT1
  },
  "output": { "dir": "out" },
  "text":   { "map": "trans_map.json", "site_map": "site_map.json", "enum_map": "enum_map.json" },
  "glossary": "glossary.csv",
  "font":   { "subset": "font/zh-subset.ttf", "source": "font/NotoSansSC-Bold.otf", "targets": {} },
  "audit":  { "severity_fail": "P1", "max_expansion_ratio": 2.5, "max_expansion_abs": 40 },
  "risk":   { "extra_patterns": [], "extra_allow": [] }
}

两个逃生口，遇到报错先想它们：

• risk.extra_patterns —— 项目里已知不能翻的串（正则）。例：^Levels$
• risk.extra_allow —— 已确认不必翻的具体串。加进去就不算漏译

术语表 glossary.csv：en,zh,forbidden 三列，forbidden 用 | 分隔同义词。CS2/CS3 依赖它，没有则跳过这两项。

判定规则：哪些串绝对不能翻

一句话版：在代码里当「键」用的串，翻了就找不到东西。

同形不同命：Pause 在设置菜单是按钮文字（该翻），在 GameInput 里是动作名（不能翻）。
靠文本形态永远分不出来，只能靠「出现在哪个类型、哪个方法」。这是 risk.py 的 _code_shape() 在做的事：

• 建对象的方法（.ctor/Build/Initialize/Create/Ensure…）里的字面量 → 名字，不翻
• 画界面的方法（Draw/OnGUI/Format/get_…）里 → 文案，翻
• 比对型方法（Is/Has/Matches/Find…）里 → 拿去匹配的键，不翻

加了新规则后必须用负向测试验证：往翻译表里故意塞一条 "Levels": "等级"，确认审计报 P0。

字体的坑

内嵌动态字体只能等长原位替换。整体重写 resources.assets 会改变 Texture2D 的 m_StreamData 偏移，贴图全错位。

流程：font 阶段按「实际用到的汉字集合」子集化，转成 TTF（Unity 对 CFF/OTF 支持不稳），再填进 m_FontData。字形数不够就减字号或压字重，不能超原尺寸。

Bangers-Regular 这类只有几十 KB 的字体放不下中文——把字体路径重定向到另一个中文字体（在 l10n.json 的 font.targets 里配），比硬塞可靠。

交付前清单

[ ] audit --fail-on P1 通过
[ ] 实际启动游戏，逐屏走一遍：主菜单 / 设置 / 存档列表 / 游戏内 HUD / 弹窗 / 报错
[ ] Player.log 无新异常（RT1 为 0）
[ ] 备份原件位置写进发布说明（还原就靠它）
[ ] 记录产物 MD5，写进版本说明

改坏了的定位方法：先只换回原 DLL、保留其他，若正常则问题一定在程序集补丁；再只换 DLL、保留其他，若复现则确认。二分比读代码快。

参考文档

• references/flow.md —— 每个阶段的详细实现与数据结构
• references/audit-spec.md —— 31 项检查的完整定义、级别、修复指引
• references/risk-rules.md —— 风险规则表与它背后的真实事故
• assets/l10n.example.json / assets/glossary.example.csv —— 配置模板