1. 项目概述为什么我们需要XUnity.AutoTranslator如果你是一个喜欢玩独立游戏或者小众Unity游戏的玩家肯定遇到过这样的烦恼一款游戏玩法绝佳美术风格独特但偏偏没有中文支持。开发者可能来自非中文地区或者游戏体量太小官方汉化遥遥无期。这时候要么硬着头皮啃生肉要么四处寻找民间汉化补丁过程繁琐且不稳定。XUnity.AutoTranslator的出现就是为了解决这个痛点。它不是一个针对特定游戏的汉化补丁而是一个通用的、运行时的文本翻译框架能够“注入”到几乎任何基于Unity引擎开发的游戏中实时拦截游戏内显示的文本调用外部翻译服务如谷歌翻译、百度翻译甚至是本地部署的AI大模型进行翻译并将结果替换回游戏界面。简单来说它就像给游戏装了一个“实时同声传译器”。这个工具的核心价值在于其通用性和可定制性。它不修改游戏原始文件而是通过一种称为“补丁”Patching或“注入”Injection的技术在游戏运行时动态工作。这意味着它兼容性极广从Steam上的热门独立游戏到一些古老的、早已停止更新的Unity作品都有可能通过它获得中文体验。对于玩家而言这是打开游戏世界语言壁垒的钥匙对于有兴趣研究游戏本地化或逆向工程的爱好者来说这也是一个绝佳的学习和实践工具。2. 核心原理与工作流程拆解要理解XUnity.AutoTranslator后文简称XUAT如何工作我们需要先了解Unity游戏是如何处理文本的。Unity游戏中的文本无论是UI上的按钮文字、对话气泡还是物品描述最终大多会通过一个核心的文本渲染组件如UnityEngine.UI.Text或TextMeshPro的text属性来设置和显示。XUAT的核心思路就是拦截对这些text属性的赋值操作。2.1 技术实现基于Harmony的运行时补丁XUAT底层依赖于一个强大的.NET补丁库——Harmony。Harmony允许在程序运行时修改已加载程序集Assembly中方法的执行逻辑。XUAT利用Harmony为Unity中负责设置文本的关键方法例如Text.set_text创建“前缀”Prefix或“后缀”Postfix补丁。当游戏尝试设置一段文本时补丁代码会先于或后于原始方法执行。在这个过程中XUAT会拦截原始文本捕获游戏试图显示的原始字符串比如英文“Start Game”。查询翻译缓存检查本地是否已经存在该原始文本对应的中文翻译。如果有直接使用缓存结果以提升性能并避免重复调用翻译API。调用翻译引擎如果缓存未命中则将原始文本发送给配置好的翻译服务如在线API或本地模型。替换并显示将获取到的翻译结果“开始游戏”返回替换掉原本要显示的原始文本。整个过程对游戏本身是透明的游戏逻辑并不知道自己显示的文本已经被“偷梁换柱”。这种方法的优势是非侵入性不会破坏游戏文件卸载也方便直接移除插件文件即可。2.2 工作流程全景图一个完整的翻译流程可以概括为以下步骤文本捕获游戏引擎调用文本显示 → 被XUAT的Harmony补丁拦截。文本处理XUAT对原始文本进行初步清理如去除富文本标签colorred这些标签需要被保留并在翻译后重新应用。缓存查询以处理后的文本为键查询本地翻译缓存文件通常是Translation.txt。翻译决策缓存命中 → 直接使用缓存译文。缓存未命中 → 根据配置调用相应的翻译端点Endpoint获取译文。译文回写与显示将最终的译文或原文如果翻译失败设置回游戏的文本组件完成显示。注意并非所有文本都能被完美捕获。一些游戏可能使用自定义的文本渲染方式、将文本编码在纹理图片中或者通过动态拼接生成文本这些情况可能会给翻译带来挑战需要额外的配置或手动处理。3. 从零开始环境准备与插件安装在开始动手之前我们需要准备好“战场”。整个过程不需要你拥有Unity编辑器或编程环境一切操作都在玩家的游戏目录中进行。3.1 工具与文件准备首先你需要确定目标游戏。找一个你希望汉化、且基于Unity引擎开发的游戏。如何判断通常可以观察游戏目录结构如果存在游戏名_Data/Managed/这样的文件夹并且里面有Assembly-CSharp.dll等文件那基本就是Unity游戏了。接下来获取XUnity.AutoTranslator插件。你需要从可靠的来源如GitHub的官方发布页下载最新的发布包Release。通常你会得到一个名为XUnity.AutoTranslator-版本号.zip的压缩包。解压后里面会包含以下核心文件和文件夹BepInEx/这是插件运行的基石框架。XUAT通常作为BepInEx插件运行BepInEx是一个Unity游戏的Mod加载器。doorstop_config.ini一个关键的配置文件用于引导游戏启动时加载BepInEx。winhttp.dllWindows或libdoorstop.soLinuxDoorstop库文件负责实际的注入过程。XUnity.AutoTranslator插件本体位于BepInEx/plugins目录下。3.2 安装步骤详解安装过程可以概括为“复制粘贴”但细节决定成败。定位游戏根目录在Steam库中右键游戏选择“管理”-“浏览本地文件”即可打开游戏安装目录。部署BepInEx框架将下载的压缩包中所有文件和文件夹特别是BepInEx文件夹、doorstop_config.ini和winhttp.dll直接复制到游戏根目录。如果系统提示有同名文件选择合并或替换通常不会有冲突。验证目录结构安装完成后你的游戏根目录应该看起来像这样GameRoot/ ├── Game.exe ├── Game_Data/ ├── BepInEx/ 新增 │ ├── core/ │ └── plugins/ │ └── XUnity.AutoTranslator/ 插件本体包含配置文件和翻译缓存 ├── doorstop_config.ini 新增 └── winhttp.dll 新增首次运行与生成配置双击启动游戏。如果一切正常游戏启动时会在控制台窗口一个黑色的命令行窗口快速闪过一些BepInEx的加载日志。进入游戏主菜单后稍等片刻然后正常关闭游戏。检查生成文件再次打开游戏根目录下的BepInEx文件夹你应该能看到插件已经生成了初始的配置文件。核心配置文件路径通常为BepInEx\plugins\XUnity.AutoTranslator\AutoTranslatorConfig.ini。同时Translation文件夹下会生成对应语言的缓存文件如zh-CN\Translation.txt初始时它是空的。实操心得第一次启动游戏后先别急着翻译直接退出。这一步的目的是让插件生成完整的目录结构和默认配置文件方便我们后续进行定制化修改。如果游戏启动崩溃很可能是BepInEx版本与游戏使用的Unity版本不兼容需要尝试更换BepInEx的版本。4. 核心配置解析让翻译引擎按你的心意工作安装只是第一步配置才是让XUAT发挥威力的关键。我们需要编辑AutoTranslatorConfig.ini文件。用任何文本编辑器如Notepad、VSCode打开它你会看到大量可配置的选项。4.1 基础与翻译端点配置找到[General]和[Service]章节进行基础设置。[General] ; 设置目标语言为简体中文 Language zh-CN ; 启用翻译缓存极大提升重复文本的加载速度 EnableTranslationCache True ; 是否在游戏内显示翻译状态如[机翻]标签调试时可开启 ShowTranslationInfo False [Service] ; 选择翻译服务端点这是最重要的设置之一 ; 可选值GoogleTranslate, BingTranslate, BaiduTranslate, YandexTranslate, DeepLTranslate, LibreTranslate, Custom Endpoint GoogleTranslateLanguage必须设置为zh-CN简体中文或zh-TW繁体中文。Endpoint这是核心。GoogleTranslate和BingTranslate通常可以直接使用但可能受网络环境影响。BaiduTranslate需要申请API密钥。如果你有本地部署的翻译API如用LibreTranslate自建服务则选择Custom并需要在下方配置自定义地址。4.2 在线翻译服务配置以百度翻译API为例如果你想使用百度翻译等需要认证的服务需要配置[BaiduTranslate]章节如果使用谷歌则配置[GoogleTranslate]章节。[BaiduTranslate] ; 是否启用使用百度时必须设为True Enabled True ; 从百度翻译开放平台申请的应用IDAPP ID BaiduAppId 你的AppId ; 从百度翻译开放平台申请的应用密钥Secret Key BaiduAppSecret 你的AppSecret申请百度翻译API步骤访问百度翻译开放平台官网注册登录。在“管理控制台”创建通用翻译API应用。获取分配给你的APP ID和密钥。将这两个值分别填入配置文件的BaiduAppId和BaiduAppSecret。注意百度翻译免费版有每秒字符数QPS限制对于游戏翻译完全够用。4.3 高级功能与性能调优继续向下翻你会看到更多精细化的控制选项。[Behaviour] ; 最大翻译文本长度超长的文本如整本书可能不会被翻译避免API出错 MaxCharactersPerTranslation 500 ; 是否翻译数字和仅包含符号的文本通常设为False避免无意义操作 IgnoreNumbers True IgnoreSymbols True [Texture] ; 是否尝试翻译游戏内的图片文字如贴图上的标语这项功能尚在实验阶段 EnableTextureTranslation False [Speech] ; 是否启用语音翻译将翻译后的文本通过TTS朗读需要额外配置 EnableSpeech FalseMaxCharactersPerTranslation非常重要。有些游戏会把大段描述文本放在一个字符串里一次性翻译可能超载。如果发现长文本未被翻译可以适当调大此值但不宜超过翻译API的单次请求限制。IgnoreNumbers建议开启。像“HP: 100”这样的文本我们只希望翻译“HP”而保留数字“100”。EnableTextureTranslation目前实用性不高且消耗资源建议保持False。性能调优建议 在[General]章节中可以找到缓存相关设置。EnableTranslationCache务必保持开启。首次游戏时翻译会稍慢因为需要联网请求。一旦翻译过的文本就会被存入本地的Translation.txt文件。第二次及以后启动游戏翻译几乎是瞬间完成的因为全部从本地缓存读取。你可以把Translation.txt文件分享给其他人他们放入对应目录就能直接获得完整汉化无需再调用API。5. 实战翻译与精细调整配置完成后再次启动游戏。你会发现在游戏过程中文本会逐渐从英文变成中文。这个过程是渐进的因为插件需要时间捕获文本并请求翻译。5.1 监控与调试为了了解插件的工作状态你可以查看日志在BepInEx文件夹下会生成日志文件LogOutput.log用文本编辑器打开可以查看详细的翻译过程包括捕获了哪些文本、调用了哪个翻译服务、是否成功等信息。这对于排查问题至关重要。启用游戏内覆盖层在配置文件中设置[General]下的EnableOverlay True并调整OverlayPosition。这样游戏画面上会显示一个小窗口实时显示正在翻译的文本和状态非常直观。5.2 手动修正与翻译缓存编辑机翻永远不可能完美。你可能会遇到翻译生硬、专有名词翻译错误比如角色名、技能名被直译、或者上下文歧义导致的错误。这时就需要手动编辑翻译缓存文件BepInEx\plugins\XUnity.AutoTranslator\Translation\zh-CN\Translation.txt。这个文件的格式非常简单原文1译文1 原文2译文2例如游戏里有一个技能叫“Shadow Strike”机翻成了“阴影罢工”看起来很怪。你可以在Translation.txt文件中找到这一行Shadow Strike阴影罢工将它修改为你认为更合适的翻译比如Shadow Strike影袭保存文件后无需重启游戏。大部分情况下XUAT支持热重载翻译缓存。你只需要在游戏中触发一下这个文本的再次显示比如重新打开技能面板就能立刻看到修正后的“影袭”。注意事项编辑Translation.txt时确保等号前后没有多余的空格并且使用UTF-8编码保存否则可能导致插件无法正确读取。对于包含特殊符号或换行符的原文编辑时要格外小心最好直接从日志文件中复制原文。5.3 处理特殊文本与正则表达式有些游戏文本是动态拼接的比如“你击败了 10 只 哥布林”。机翻可能会分别翻译“你击败了”、“只”、“哥布林”导致语句破碎。XUAT支持使用正则表达式Regex来匹配和翻译这种模式。在Translation文件夹下你可以创建一个名为Regex.txt的文件。在里面你可以这样写你击败了 (\d) 只 (.*?)You defeated $1 $2这只是一个简单示例实际的正则表达式需要根据游戏文本的具体模式来编写。这属于进阶用法需要对正则表达式有一定了解。但对于大多数游戏直接编辑Translation.txt已经足够解决90%的翻译质量问题。6. 常见问题排查与进阶技巧即使按照指南操作你也可能会遇到一些“坑”。这里记录了一些常见问题及其解决方案。6.1 游戏启动崩溃或插件未加载问题现象可能原因解决方案游戏完全无法启动闪退。1. BepInEx版本与游戏Unity版本不兼容。2.winhttp.dll与系统或游戏冲突。1. 尝试更换BepInEx版本如从5.x换到6.x或使用针对特定Unity版本的BepInEx变体。2. 尝试使用version.dll或unitydoorstop等其他的注入方式在BepInEx发布页通常有备选方案。游戏能启动但无翻译效果BepInEx/plugins下无XUAT日志。1. Doorstop注入失败。2. 插件文件放置位置错误。1. 检查doorstop_config.ini中的targetAssembly路径是否正确指向BepInEx\core\BepInEx.Preloader.dll。2. 确保XUAT的插件文件夹在BepInEx/plugins/下而不是在BepInEx/plugins外或更深层级。控制台窗口一闪而过游戏正常启动但无翻译。游戏可能以管理员权限运行与注入器冲突。尝试以管理员身份运行游戏或者关闭游戏的“以管理员身份运行”属性。6.2 翻译不生效或部分文本未翻译问题现象可能原因解决方案部分UI文字翻译了但剧情对话全是英文。1. 对话文本可能由自定义的文本系统渲染未被标准补丁捕获。2. 文本可能以其他编码形式存在。1. 在配置文件中启用实验性功能如尝试启用[Behaviour]下的UseRedirectionHelper如果存在。2. 检查日志文件看是否捕获到了这些对话文本。如果没有可能需要更高级的补丁或手动提取文本。翻译结果全是乱码。1. 目标语言设置错误。2. 翻译API返回编码问题。3. 游戏字体不支持中文。1. 确认Language zh-CN。2. 尝试更换翻译端点如从谷歌换到百度。3. 这是Unity游戏汉化的经典问题。需要为游戏添加中文字体。这通常涉及更复杂的Mod制作需要找到游戏的字体资源文件并进行替换。翻译速度极慢游戏卡顿。1. 网络延迟高使用在线API时。2. 未开启翻译缓存每次都在重复翻译。3. 一次性捕获了海量文本。1. 使用本地翻译模型如配置LibreTranslate本地端点或换用响应更快的API。2. 确认EnableTranslationCache True。3. 适当调小MaxCharactersPerTranslation或检查是否有文本陷入重复翻译的死循环。6.3 进阶技巧使用本地AI大模型进行翻译对于网络环境不佳或追求更高翻译质量的用户配置本地翻译服务是一个终极方案。这里以使用LibreTranslate一个开源的机器翻译引擎自建服务为例部署LibreTranslate你可以通过Docker轻松运行它docker run -ti --rm -p 5000:5000 libretranslate/libretranslate。这会在本地的5000端口启动一个翻译API服务。配置XUAT在AutoTranslatorConfig.ini中进行如下设置[Service] Endpoint Custom [Custom] ; 你本地LibreTranslate服务的地址 Url http://127.0.0.1:5000/translate ; 请求方法LibreTranslate使用POST Method POST ; 请求体格式LibreTranslate需要JSON RequestBodyFormat Json ; 定义JSON请求体的模板{0}是源语言{1}是目标语言{2}是要翻译的文本 RequestBody {q: {2}, source: {0}, target: {1}} ; 定义如何从JSON响应中提取翻译结果这里对应响应中的translatedText字段 ResponseTranslationPath translatedText设置语言映射在[Custom]章节下可能需要添加SourceLanguage和TargetLanguage的映射例如SourceLanguage enTargetLanguage zh。这样一来所有翻译请求都会发送到你本地的服务器完全离线速度极快且隐私有保障。你甚至可以部署更强大的本地AI模型来获得媲美专业译者的质量。6.4 翻译缓存的管理与分享Translation.txt文件是你的劳动成果。定期备份这个文件是个好习惯。当你重装游戏或更换电脑时只需把备份的Translation.txt放回原处就能立刻恢复完整的汉化。这个文件也是社区分享的基础。你可以将精心校对过的Translation.txt分享给其他玩同一款游戏的玩家他们放入自己的插件目录就能享受成果这构成了民间汉化社区的一种高效协作模式。在分享前建议清理一下文件中可能包含的个人信息或无关的测试条目。整个使用XUnity.AutoTranslator的过程是一个从“开箱即用”到“深度定制”的旅程。它降低了非官方汉化的技术门槛将权力交还给玩家社区。虽然机翻的起点可能粗糙但通过社区成员的共同校对和修正完全有可能产出一份质量上乘的本地化补丁。这个过程本身也是理解和参与游戏创作的一种独特方式。