1. 项目概述：为什么Unity游戏实时本地化是个“痛点”？

做独立游戏或者小型工作室的朋友，估计都遇到过这个头疼的问题：游戏做完了，想出海，想多卖几份，就得做多语言本地化。传统的本地化流程是什么？策划和翻译把游戏里所有文本导出一个Excel或者JSON文件，翻译团队吭哧吭哧翻完，程序再把这些文本一个个填回游戏里，测试跑一遍看看有没有漏翻、错位或者UI撑爆了。整个过程周期长、成本高，而且一旦游戏更新，加了新内容，又得从头再来一遍。对于内容量大的游戏，或者还在频繁更新、添加新对话的EA（抢先体验）阶段游戏，这简直是噩梦。

所以，“实时本地化”这个概念就变得非常有吸引力。简单说，就是游戏在运行时，能自动识别并翻译游戏界面、对话、物品描述等文本，玩家甚至能即时切换语言，而无需等待官方发布新的语言包。这不仅能极大缩短多语言版本的发布周期，还能让社区模组制作者（Modder）更方便地制作非官方语言包，甚至为一些“生肉”（无官方汉化的）游戏提供即时翻译的可能。

而XUnity.AutoTranslator正是解决这个痛点的利器。它不是一个官方的Unity插件，而是一个由社区开发者bbepis创建并维护的、基于BepInEx（一个Unity游戏的模组框架）的插件。它的核心能力就是在游戏运行时，拦截游戏引擎渲染的文本，调用外部翻译API（如谷歌翻译、百度翻译、DeepL等）或者查询本地词典进行翻译，并将翻译结果“覆盖”显示在原文本之上。对于开发者，你可以用它来快速构建多语言原型、进行本地化测试；对于玩家和模组爱好者，你可以用它来“啃生肉”或者制作分享翻译补丁。

2. 核心原理与架构拆解：AutoTranslator是如何“无痕”替换文本的？

要理解怎么用，先得明白它怎么工作。Unity游戏中的文本，最终大多是通过UnityEngine.UI.Text或TextMeshPro（TMP）组件显示在屏幕上的。这些组件在设置其text属性时，就会触发渲染更新。

XUnity.AutoTranslator的核心思路是“劫持”或“监听”这些文本设置的操作。它主要依赖于BepInEx提供的补丁（Patching）能力，具体来说是使用 HarmonyLib 这个库进行方法前缀（Prefix）或后置（Postfix）补丁。简单类比，就像是在游戏调用“设置文本”这个函数的时候，安插了一个“中间人”。

2.1 工作流程详解

1. 文本拦截：当游戏代码执行到类似textComponent.text = “Hello World”;这样的语句时，被AutoTranslator注入的补丁代码会先一步截获这个调用。它拿到了原始文本 “Hello World”。
2. 翻译查询：插件会检查是否已经为 “Hello World” 这个字符串生成过翻译并缓存了。如果有，直接进入下一步。如果没有，则启动翻译流程。
3. 翻译流程：
   • 本地词典优先：插件首先会在其配置的本地翻译文件（通常是Translation.txt）中查找是否有对应的翻译。这个文件格式是原文=译文。这是离线翻译和社区翻译包分发的核心。
   • 调用在线API：如果本地词典未命中，且配置了在线翻译服务（如Google Translate），插件会将原文发送到对应的翻译API，获取译文。
   • 结果缓存：无论来自本地还是在线，获取到的译文都会被缓存到内存和一个本地缓存文件（如Cache.db）中。下次再遇到相同的原文，就直接使用缓存，避免重复请求，提升性能并减少API调用次数。
4. 文本替换：插件将获取到的译文，通过某种方式“设置”回UI组件。这里有个关键点：为了不影响游戏原始逻辑（比如一些代码可能依赖原始文本进行判断），AutoTranslator通常不会直接修改textComponent.text的原始值，而是采用“覆盖渲染”的方式。对于UGUI Text，它可能会复制一个相同的Text组件叠在上面显示译文；对于TextMeshPro，手段可能更底层一些，直接修改顶点缓冲或材质属性。最终给玩家看到的，就是翻译后的文本，而游戏逻辑代码读到的，还是原始文本。
5. UI适配：翻译后的文本长度很可能与原文不同，可能导致UI布局错乱（比如按钮文字溢出）。AutoTranslator提供了一些基础的自适应功能，比如自动调整文本框大小，但对于复杂的UI，仍可能需要手动调整或依赖游戏原有的UI布局系统。

2.2 插件核心组件

• BepInEx：基石。它是一个Unity游戏的插件/模组加载框架，为AutoTranslator提供了运行环境和注入游戏代码的能力。没有它，AutoTranslator无法独立工作。
• XUnity.AutoTranslator：主插件。包含文本拦截、翻译调度、缓存管理、配置读取等核心逻辑。
• XUnity.ResourceRedirector：可选但重要的依赖插件。它提供了更强大的资源重定向能力。有些游戏的文本不是动态设置的，而是直接写在预制体（Prefab）或资产包（AssetBundle）里。ResourceRedirector可以拦截这些资源的加载过程，实现对静态文本的翻译。这对于翻译游戏启动界面、菜单等静态UI元素至关重要。
• 翻译端点插件：例如XUnity.AutoTranslator-BaiduTranslate、XUnity.AutoTranslator-GoogleTranslate等。这些是连接具体翻译服务的适配器。主插件定义了翻译接口，这些端点插件负责实现与特定API的通信。

3. 环境准备与安装部署：手把手搭建翻译环境

理论懂了，我们来实操。假设我们要为一个名为MyUnityGame.exe的PC游戏安装实时翻译。这里以Windows平台为例。

3.1 前期准备与工具下载

1. 确认游戏运行环境：首先确保你的游戏是基于.NET Framework或.NET（Core）的Mono/IL2CPP脚本后端。绝大多数Unity游戏都符合。查看游戏目录下是否有UnityPlayer.dll、GameAssembly.dll（IL2CPP）或Mono相关dll。
2. 下载BepInEx：前往BepInEx的GitHub发布页，下载对应你游戏架构的版本。通常x86游戏下载BepInEx_x86_version.zip，x64游戏下载BepInEx_x64_version.zip。如果不确定，可以尝试x64版本，现在大部分游戏都是64位。
3. 下载XUnity.AutoTranslator：前往其GitHub发布页，下载最新版本的XUnity.AutoTranslator-BepInEx-5.4.zip（确保版本与BepInEx 5.x兼容）。
4. 下载翻译端点插件：例如，你想用百度翻译，就下载XUnity.AutoTranslator-BaiduTranslate-版本号.zip。用谷歌翻译就下载对应的谷歌插件。如果主要用本地词典，可以不下载在线端点，但建议备一个以防万一。
5. （可选）下载Resource Redirector：如果游戏有大量静态UI文本，建议下载XUnity.ResourceRedirector-版本号.zip。

3.2 安装步骤详解

注意：安装前最好备份游戏原始文件，或确认游戏支持Steam的“验证文件完整性”功能，以便回退。

1. 安装BepInEx：

   • 将下载的BepInEx_x64_version.zip全部文件解压到游戏根目录（即MyUnityGame.exe所在的文件夹）。
   • 首次运行游戏。双击MyUnityGame.exe启动游戏，等待游戏完全启动到主菜单后再关闭。这个过程会让BepInEx完成初始化和目录生成。
   • 关闭游戏后，你会发现游戏根目录下多出了一个BepInEx文件夹，里面包含core、plugins等子目录。BepInEx\plugins就是我们放插件的地方。

2. 安装AutoTranslator主插件：

   • 解压XUnity.AutoTranslator-BepInEx-5.4.zip。你会看到类似这样的结构：BepInEx\plugins\XUnity.AutoTranslator。
   • 将解压出的BepInEx文件夹整体拖到游戏根目录，合并并覆盖原有的BepInEx文件夹。确保XUnity.AutoTranslator.dll等文件位于游戏根目录\BepInEx\plugins\XUnity.AutoTranslator\下。

3. 安装翻译端点插件：

   • 解压你下载的端点插件，例如百度翻译。同样会看到一个BepInEx文件夹。
   • 将其合并到游戏根目录的BepInEx文件夹中。通常端点插件的dll会放在BepInEx\plugins\XUnity.AutoTranslator\Plugins\或类似的子目录下。请根据压缩包内的实际结构放置。

4. 安装Resource Redirector（可选）：

   • 步骤同上，解压合并到游戏根目录的BepInEx文件夹。

5. 最终目录结构检查：

   • 游戏根目录下应有：MyUnityGame.exe,UnityPlayer.dll,BepInEx\,MonoBleedingEdge\等。
   • BepInEx\plugins\下应有XUnity.AutoTranslator文件夹。
   • XUnity.AutoTranslator文件夹内应有XUnity.AutoTranslator.dll,config.ini, 以及Plugins\文件夹（里面是端点插件dll）。

3.3 初始配置与测试

1. 启动游戏生成完整配置：再次启动游戏。如果一切正常，游戏应该能启动，并且BepInEx的控制台窗口（一个黑色命令行窗口）可能会弹出，显示加载的插件信息。进入游戏主菜单后退出。
2. 定位配置文件：现在去BepInEx\config文件夹，你会找到AutoTranslatorConfig.ini（主配置）和以插件命名的其他ini文件（如BaiduTranslate.ini）。
3. 配置在线翻译（以百度翻译为例）：
   • 打开BaiduTranslate.ini。
   • 你需要百度翻译开放平台的API密钥。前往百度翻译开放平台注册开发者账号，创建通用翻译服务，获取AppId和SecretKey。
   • 在配置文件中找到如下字段并填写：

     [Baidu] # 从百度开发者控制台获取 SecretKey=你的SecretKey AppId=你的AppId

   • 保存文件。
4. 配置基础行为：打开AutoTranslatorConfig.ini，关注以下关键设置：

   [General] # 启用翻译 EnableTranslation=true # 翻译语言，例如简体中文 Language=zh # 源语言，通常为auto SourceLanguage=auto [Behaviour] # 是否自动翻译新发现的文本 AutoTranslateOnCreate=true # 翻译结果缓存到本地 EnableTranslationCache=true # 是否将未命中的在线翻译结果自动追加到本地词典文件 EnableTranslationFileAppend=true [Text] # 最大同时翻译请求数，防止刷爆API MaxConcurrentTranslations=3 # 翻译文本的最大长度（字符），超长文本可能被截断或分次翻译 MaxCharactersPerTranslation=500

5. 测试翻译：配置完成后，再次启动游戏。尝试浏览游戏内的各种界面、对话。观察文本是否被替换为中文。第一次翻译某个句子时可能会有轻微延迟（等待API返回），翻译成功后，该结果会被缓存，后续再出现就是瞬间切换。

4. 高级配置与深度定制：从能用变到好用

基础安装只是第一步，要让翻译体验完美，还需要进行大量精细化的配置和定制。

4.1 本地词典（Translation.txt）的魔力

在线翻译虽然方便，但质量不稳定，特别是游戏领域的专有名词（技能名、地名、角色名）、俚语和语境化表达。本地词典是保证翻译质量和一致性的终极武器。

• 文件位置：BepInEx\translations\zh\Text\Translation.txt（假设目标语言是中文）。如果文件夹不存在，运行一次游戏并尝试翻译后会自动生成。
• 格式：每行一条，格式为原文=译文。例如：

  Attack=攻击 Potion of Healing=治疗药水 The ancient dragon awakens.=古龙苏醒。

• 优先级：本地词典的优先级高于在线翻译。只要在词典里找到匹配项，就不会去请求在线API。
• 词典管理技巧：
  • 增量积累：开启EnableTranslationFileAppend=true后，所有通过在线API翻译的文本都会自动追加到Translation.txt文件末尾。你可以定期整理这个文件，修正错误的翻译，形成自己的高质量词典。
  • 版本控制与分享：这个Translation.txt就是你的翻译补丁。可以分享给其他玩家，他们只需要把这个文件放到对应语言的目录下，就能获得完全一致的翻译体验，无需重复调用API。
  • 正则表达式支持：AutoTranslator支持在词典中使用正则表达式进行模糊匹配，这对于翻译动态生成的文本（如“你获得了 5 金币”）非常有用。例如：

    You received (\d+) gold\.=你获得了$1金币。

4.2 处理特殊文本与排除项

不是所有文本都适合翻译，比如：

• 代码、文件名、路径：翻译了会导致游戏崩溃或功能异常。
• 玩家输入框内的文本：翻译了会覆盖玩家的输入。
• 某些作为关键字的文本：比如一些物品ID，翻译了可能导致游戏无法识别。

可以在AutoTranslatorConfig.ini中配置排除规则：

[Text] # 使用正则表达式排除文本 ExcludedTextRegex=^[A-Za-z0-9_\\/\\.:-]+$|^\\d+$|^Player$|^InputField

这个例子排除了纯英文数字组合、纯数字、以及包含“Player”、“InputField”的文本。

4.3 字体与UI适配问题

这是实时本地化最大的挑战之一。英文字体通常很紧凑，中文字体较宽，直接替换可能导致：

• 文本溢出：按钮文字显示不全。
• 布局错乱：自动布局的UI元素挤在一起或重叠。
• 字体缺失：游戏自带的字体不包含中文字形，导致显示为方块（口口口）。

解决方案：

1. 字体补丁：使用AssetBundle加载或Resource Redirector替换游戏默认字体为一个包含多语言字符集的字体（如思源黑体、Noto Sans）。这需要一定的Unity Mod开发知识，可以寻找社区已经做好的字体Mod。
2. UI缩放与适配：AutoTranslator内置了简单的文本框尺寸自动调整，但对于复杂UI效果有限。更高级的做法是使用专门的UI重排Mod，或者通过Resource Redirector修改UI预制体的布局参数。
3. 手动调整词典：对于已知会出问题的短文本（如按钮上的“OK”、“Cancel”），可以在本地词典中为其指定一个更短的翻译，或者直接保留原文。

4.4 性能优化与缓存策略

实时翻译毕竟有开销，在低配电脑或文本密集场景（如大量NPC对话同时刷新）可能引起卡顿。

• 调整并发数：MaxConcurrentTranslations不宜设置过高，通常2-5即可。太高会瞬间发出大量网络请求，可能被API限流或导致游戏卡顿。
• 善用缓存：EnableTranslationCache=true务必开启。缓存文件（如Cache.db）会保存在插件目录下。一旦翻译过，下次启动游戏就无需联网。
• 预翻译与离线包：对于打算正式发布的社区翻译包，最佳实践是：
  1. 在开发环境，使用在线API跑遍游戏所有文本，生成完整的Translation.txt和缓存。
  2. 仔细校对和润色Translation.txt中的翻译。
  3. 发布时，只分发Translation.txt和可能需要的字体文件，并指导用户关闭在线翻译（EnableTranslation=false）。这样用户获得的是高质量、零延迟、完全离线的翻译体验。

5. 实战问题排查与经验心得

在实际使用和帮助他人配置的过程中，我踩过不少坑，也总结了一些“教科书里没有”的经验。

5.1 常见问题速查表

5.2 实操心得与进阶技巧

1. “先离线，后在线”策略：对于新游戏，我习惯先不配置在线API，直接进游戏。让插件生成基本的配置和目录结构。然后，我会去游戏社区（如Nexus Mods, GitHub）寻找是否已有玩家共享的Translation.txt词典文件。如果有，直接使用，质量往往远高于机翻。没有的话，再考虑配置在线翻译作为采集工具。
2. 日志是你的好朋友：BepInEx的日志文件LogOutput.log和游戏运行时按F5调出的控制台，包含了插件加载、文本拦截、翻译请求的所有详细信息。遇到问题第一件事就是看日志，错误信息通常非常直白。
3. 分阶段构建词典：不要试图一次性翻译整个游戏。可以先专注于主菜单、设置界面、技能描述等核心部分，构建一个基础可用的词典。然后随着游戏进程，逐步添加新区域的翻译。利用EnableTranslationFileAppend功能，让在线翻译帮你“捕捉”漏网之鱼，然后你定期去Translation.txt里进行批量校对和润色。
4. 处理动态文本的“占位符”：很多游戏文本像“对<color=red>目标 造成<color=yellow>50 点伤害”。直接翻译可能会破坏HTML标签。AutoTranslator通常能较好地处理这种内嵌富文本标签，但为了保险，可以在词典中使用正则表达式精确匹配可变部分：Deals <color=yellow>(\d+)</color> damage to <color=red>(.+?)</color>.=对<color=red>$2</color>造成<color=yellow>$1</color>点伤害。
5. 为Modders准备的提示：如果你是一名模组开发者，想要让自己的Mod支持AutoTranslator，最好的做法是在你的Mod中直接集成一个Translation.txt文件，并在插件初始化时引导用户将其放入正确的翻译目录。你甚至可以提供不同语言的版本。这能极大提升你的Mod的国际化友好度。

最后，我想强调的是，XUnity.AutoTranslator是一个极其强大的工具，但它不是一个“魔法棒”。它实现了翻译的自动化和实时化，但翻译质量的上限依然取决于本地词典的精心维护。它更像是一个桥梁，连接了游戏原始内容和社区贡献的智慧。对于开发者，它是快速原型验证的利器；对于玩家社区，它是打破语言壁垒、共享游戏乐趣的基石。花时间打理好你的Translation.txt，你收获的不仅仅是一个翻译好的游戏，更是一份可以惠及他人的成果。