XUnity.AutoTranslator 不翻译怎么办

XUnity.AutoTranslator 是免费的、MIT 许可的、在持续维护的，也是 Unity 上最好的那个运行时翻译工具。它的工作方式，是挂钩游戏把一条字符串交给文本组件的那一刻，在它被画出来之前换成译文。这个设计正是它完全不需要了解游戏文件格式的原因 —— 同样也是它失败时会悄无声息地失败的原因。什么都不崩。游戏就是照旧跑日语。

下面这五件事几乎解释了每一份"它不翻译"的报告。按顺序逐条排查；每一条的修法都不一样，在它们之间瞎猜会白白耗掉很多个晚上。

第一步：看日志，不要看画面

插件对自己在做什么很张扬，而日志是它唯一说话的地方。用 BepInEx 安装时，看 BepInEx/LogOutput.log。Unity 自己的日志就在旁边：较老的构建在 <Game>_Data/output_log.txt，较新的在 %APPDATA%/../LocalLow/<Company>/<Game>/Player.log。

• 日志里到底有没有提到 XUnity.AutoTranslator 被加载？如果没有，问题出在加载器，而不是翻译器 —— 你碰上的是失败模式一。
• 它有没有列出某个端点被初始化，而后又提到某个端点在反复报错之后被关闭？那是失败模式五。
• 译文有没有被写进 BepInEx/Translation/<lang>/Text/_AutoGeneratedTranslations.txt？如果那个文件正在被正确的译文填满，屏幕上却从来看不到，那么网络那一侧是好的，显示那一侧不是。
• 在游戏里按 ALT+1 打开翻译汇总窗口。如果它显示出你正盯着的那些行，说明挂钩看得见它们。如果它一直是空的，说明挂钩从来没看见过它们。

最后那个分岔 —— "翻译了但没显示"对比"从来没被看见" —— 就是路口。下面的一切都挂在它上面。

1. 游戏是 IL2CPP 构建

Unity 用两种非常不同的运行时发布游戏。Mono 把游戏的 C# 保留成 <Game>_Data/Managed/ 里普通的 .NET 程序集，Assembly-CSharp.dll 也在其中，类型名和方法名都完整保留。IL2CPP 则提前把那些 C# 转成 C++ 并编译进一个原生的 GameAssembly.dll；类型系统里活下来的部分被打包进 <Game>_Data/il2cpp_data/Metadata/global-metadata.dat。

一个运行时挂钩需要找到一个方法并把它替换掉。在 Mono 上这是一个普通的反射问题。在 IL2CPP 上根本没有托管方法可供反射 —— 代码是原生的，回到名称、字段和方法地址的唯一办法，是解析 global-metadata.dat 并重建布局。那是一个完全不同的加载器，不是一个设置项。

• 五秒钟怎么判断：游戏 exe 旁边有 GameAssembly.dll，外加一个 il2cpp_data 文件夹，就是 IL2CPP。一个装满 DLL 的 Managed/ 文件夹就是 Mono。
• IL2CPP 需要 IL2CPP 版的 BepInEx，以及针对它构建的那一版 XUnity.AutoTranslator。Mono 版根本不会加载 —— 它只是不出现在日志里，而这看起来和"插件坏了"一模一样。
• 位数也要对。64 位游戏需要 64 位加载器。配错的一对会以同样安静的方式失败。
• 有些游戏发布的元数据文件解析不了。加壳和防篡改层会加密或重排 global-metadata.dat，而每一个依赖读取它的工具 —— 包括这个挂钩 —— 都到此为止。

2. 插件加载了，文字却从来不出现

插件在日志里，端点初始化了，_AutoGeneratedTranslations.txt 也在变长 —— 屏幕却没变。要么挂钩翻译的是一条游戏随后丢掉的字符串，要么游戏是通过挂钩拦不到的路径来设置文本的。

TextGetterCompatibilityMode

有不少游戏会回读自己刚设置的文本 —— 为了测量它、往后追加，或者拿它跟别的东西比较。一旦组件里装的是译文，这次回读返回的就是译文，游戏自己的逻辑于是在一段它没写过的文本上运作，结果从一行文字被还原到整个布局塌掉都有可能。AutoTranslatorConfig.ini 里的 TextGetterCompatibilityMode 会让 getter 把原始字符串还给游戏，而玩家看到的仍然是译文。它默认关闭，因为每一次读取都要为它付出代价；当文字闪烁、还原或者怎么都留不住时，它是第一个该试的开关。

这一类的另一半，是文本压根就不经过任何被挂钩的 API：游戏用自己的文本引擎渲染、直接把字符流进一个网格，或者把对话烘焙进一张图。那种情况没有配置可言 —— 拦截点根本不存在。画进美术图里的文字则完全是另一个问题，需要的是图片文字翻译，而不是任何挂钩。

3. 只有一部分文字被翻译

菜单翻了，对话没翻。或者对话翻了，每一个按钮还是日语。这几乎总是某个 UI 框架没被启用，因为插件对每一个框架分别挂钩，而它们并非全都默认开着。

• 默认开启：UGUI（Unity 内置 UI）、NGUI、TextMeshPro 和 UIElements（EnableUGUI、EnableNGUI、EnableTextMeshPro、EnableUIElements）。它们加起来覆盖了大多数现代游戏，也包括 Utage 这类视觉小说框架——它们本身没有自己的开关，而是通过上面这些框架来绘制。
• 默认关闭：IMGUI 和旧版 TextMesh 组件。IMGUI 是 Unity 的即时模式 GUI —— 它每一帧都重绘，所以挂钩它意味着每一帧都翻译，它被禁用是出于性能考虑，而不是因为它不管用。
• 这些开关住在 `AutoTranslatorConfig.ini` 里，名字是 EnableIMGUI、EnableTextMesh 等等。把你游戏用到的那一个设成 True，然后重启。
• 较老的游戏和日本同人 Unity 作品是 IMGUI 的常客。如果一款游戏的菜单看起来就是一堆默认样式的灰色方框，那是很强的线索。

如果全部启用之后什么都没变，那么这些文字根本不是经由 Unity 文本组件出来的 —— 回到失败模式二。

4. 长行是被跳过，不是被翻译

MaxCharactersPerTranslation 默认是 200。任何更长的都会被跳过。不是截断，不是重试，也不是以你玩着玩着能注意到的方式记进日志 —— 就是跳过，于是那一行以原语言渲染，而且看不出哪里坏了。

这是人们找得最久的一种失败模式，因为证据太弱：游戏大部分都翻了，然后有那么一段没翻。视觉小说是常见的受害者 —— 一大段旁白，或者一段中间没有换行的独白，轻轻松松就超过 200 字符，而那恰恰是你最想读到译文的地方。

在 AutoTranslatorConfig.ini 里把这个值调高，然后重启。要记得你同时也在抬高每一次请求的成本：免费端点各自有每次请求的长度上限，会开始拒绝单条超出上限的请求，所以一个非常大的值，等于用一次安静的跳过换来一个显眼的端点报错。500–1000 之间的某个值足以覆盖普通的 VN 文风。

5. 端点失败了，或者对你限流了

XUnity 的默认端点是一些免费的公共翻译服务，访问方式和浏览器访问它们的方式一样。它们没有任何契约保障，而且会变。当一连串请求接连失败时，插件会在本次会话剩下的时间里把那个端点关掉，而不是继续猛敲 —— 这是个有意为之的好决定，但也意味着从那一刻起，一切都会安静地保持未翻译状态，直到你重启游戏。

• 在日志里找那行关闭记录。如果它在，那么修法是重启外加改点什么 —— 而不是继续等。
• 把队列放慢。MaxTranslationsQueuedPerSecond 和那些延迟设置之所以存在，是因为触发限流的正是突发流量。在 VN 里快进，几秒钟就能发出几百条请求。
• 换个端点。如果某个免费服务今天状态不好，另一个通常没事。
• 用带密钥的端点。一个真正的 DeepL 或付费 API 密钥能消除这一整类问题，代价是它是一个付费 API 密钥。
• 更新插件。当某个免费端点的协议变了，修复是以一个新版本的形式到来的。拿一个两年前的构建去打一个已经改过的服务，是"以前明明能用"的常见原因。

附加：文字翻译了，却渲染成方块

这一条根本不是翻译失败。游戏发布时带的字体图集，只包含它原语言需要的那些字形，而你的目标语言需要的字形不在里面，于是每一个缺失的字符都画成一个方块或者空白。XUnity 正是为此提供了 OverrideFont 和 OverrideFontTextMeshPro。注意这个指纹：方块意味着缺字形；字面的 `?` 字符意味着链条更早处的编码问题。它们是不同的 bug，而字体设置只修得了前一个。

该按什么顺序排查

1. 找 GameAssembly.dll 来确认是 Mono 还是 IL2CPP，并确认你装的是对应的加载器。
2. 打开 BepInEx/LogOutput.log，确认插件加载了、端点初始化了。
3. 在游戏里按 ALT+0 打开插件自己的窗口——什么都没出现，说明插件没加载。ALT+1 打开 Translation Aggregator：空的说明挂钩从没看见那些文字，有内容说明它看见了。
4. 如果挂钩看得见、屏幕却不变，打开 TextGetterCompatibilityMode。
5. 如果只有一部分游戏被翻译，启用 IMGUI 和旧版 TextMesh。
6. 如果是特定的长行一直没翻，把 MaxCharactersPerTranslation 从默认的 200 调高。
7. 如果是玩到一半全都停了，找那行端点关闭记录，然后用更慢的队列或另一个端点重启。

什么时候挂钩这条路本身就不对路

上面每一种失败都能追回同一个根源：一个运行时挂钩只能翻译它在场拦得到的文本。如果游戏不是通过插件认识的 API 来设置字符串，或者文字在插件加载之前就画出来了，或者运行时根本不暴露可挂钩的方法，那就没有什么可配置的。工具在正确地做它该做的事，文字只是够不着。

结构上的另一条路，是去处理文件，而不是处理画面。一个文件级工具打开游戏自己的资源，把字符串拉出来、翻译掉，再写出一份译好的游戏副本 —— 于是在引擎加载之前，文字已经是目标语言了。没有挂钩，没有拦截点，没有逐框架的开关，字符上限就是格式本身能装下的量。这正是 RuneTranslate 在 Unity 以及另外 16 种引擎和格式上做的事。

取舍是真实存在的，而且方向相反。一个文件级工具只够得到在文件里的文本 —— 对 Unity 而言，这意味着 TextAsset、MonoBehaviour 字符串字段、StreamingAssets 脚本、本地化表和资源包，包括 AES 加密的 Addressable 资源包。它需要在你开玩之前先做一步导出，而不是边玩边翻。而且对于游戏在运行时用碎片拼出来的文本，它无能为力。Unity 正是因此被列为尽力而为的引擎：不同游戏外部化多少内容差别极大，而打开项目这一步，会告诉你手上是哪一种。

• 编译进 C# 代码里的文本是那条硬边界。在 Mono 构建上，RuneTranslate 用一个捆绑的附属程序从游戏程序集里读出字符串字面量，并以调用点拿它做什么来把关，所以它绝不会去翻译一个场景名或一个动画参数。在 IL2CPP 构建上，编译过的代码不在范围内。
• 不过 IL2CPP 的资源文本没问题。组件字符串字段在 IL2CPP 上通过从游戏元数据重建类型信息来读取 —— 用的正是挂钩需要的那个 global-metadata.dat，只是用途不同。
• 它读得懂 XUnity 自己的输出。如果你已经有一个填好的 _AutoGeneratedTranslations.txt，RuneTranslate 会解析那个文件，并可以翻译里面的值，键原封不动。你已经做过的工作不会被扔掉。
• 字体在导出时处理，办法是往游戏里注入一个后备字体资源，让原字体从未覆盖过的目标语言也能渲染出来。

九个翻译服务，其中三个完全不需要 API 密钥 —— Google、免费 DeepL，以及 DeepL 的 Classic / Next-gen 模型 —— 另外还有 DeepL 的 API、OpenAI、Anthropic、DeepSeek、任意 OpenAI 兼容端点，以及通过 Ollama 或 LM Studio 跑的本地模型。免费档位解锁每一种引擎和每一个翻译服务；它限的是吞吐，并且同时只持有一个项目。支持 Windows 10/11，或在 Wine、Proton 下的 Linux 和 Steam Deck。首次启动需要一个免费的 Patreon 登录。产出是一份归你保留、可直接游玩的翻译构建。

两种做法都不是普适正确的。一款整个剧本都放在一张打包 JSON 表里的游戏，本来就是文件级的活。一款在运行时用代码拼出对话的游戏，本来也永远是挂钩的活。分清你手上是哪一种，就是这件事的大半。

接下来看什么

• 如何翻译 Unity 游戏 —— 完整走一遍，包括 Unity 会外部化什么、不会外部化什么。
• Unity 引擎页面 —— 支持的格式和当前的局限，都在一处。
• RuneTranslate 对比 XUnity.AutoTranslator —— 两种做法并排放，以及各自赢在哪些场景。
• 怎么挑翻译服务 —— 哪些翻译服务擅长处理日语文风，哪些一分钱不花。
• 术语表入门 —— 让角色名和术语在整个剧本里保持一致。
• 全部受支持的引擎 —— 万一这游戏最后根本不是 Unity。