1. 项目概述为什么我们需要为Unity游戏实现实时翻译如果你是一个喜欢玩各种独立游戏或者小众Unity游戏的玩家或者你本身就是一个Unity开发者那么“语言不通”这个问题你一定深有体会。很多优秀的游戏尤其是那些由小型团队或个人开发者制作的往往首发只有英文或日文版本。等一个官方的中文补丁可能遥遥无期。这时候一个能在游戏运行时实时将屏幕上的外文文本替换成中文的工具就成了“救星”。XUnity AutoTranslator通常被简称为XUnity自动翻译器就是这样一个在玩家社区中广为流传的神器。简单来说它是一个基于BepInEx插件框架的Unity游戏Mod模组。它的核心功能是“劫持”游戏在屏幕上绘制文本的调用将原始文本比如英文发送到指定的在线翻译服务如谷歌翻译、百度翻译、DeepL等获取翻译结果后再将其渲染到屏幕上从而实现近乎实时的游戏内文本翻译。这听起来有点像“外挂”但它不修改游戏逻辑只干预文本渲染流程目的纯粹是为了消除语言障碍。这个工具的价值远不止于“玩家爽玩”。对于开发者而言它提供了一个极佳的研究样本你可以通过它学习Unity的文本渲染管线、IL代码注入Hook技术、异步网络请求在游戏中的处理以及如何设计一个灵活、可配置的插件架构。无论你是想为自己的游戏快速制作一个多语言原型还是想深入理解Unity Mod开发这个项目都是一个绝佳的切入点。接下来我将以一个资深Mod开发者和Unity技术爱好者的视角带你彻底拆解XUnity AutoTranslator的实现原理、部署方法、核心配置以及那些官方文档里不会写的“踩坑”实录。2. 核心原理深度拆解文本是如何被“劫持”并替换的要理解XUnity自动翻译器如何工作我们需要深入到Unity引擎的运行时层面。Unity游戏中的文本显示绝大多数情况下是通过UnityEngine.UI.Text组件或TextMeshPro组件来完成的。这些组件在每帧更新时会将其text属性的内容提交给底层的渲染系统进行绘制。2.1 Hook技术在关键位置“插入”我们的逻辑XUnity自动翻译器的核心手段是“Hook”钩子或者更专业地说是“方法拦截”。它并不直接修改游戏的原生DLL文件而是在游戏运行时通过BepInEx框架提供的强大能力将我们自己的代码“注入”到游戏进程的关键函数调用中。具体到文本翻译它主要Hook了两个地方UI.Text组件的text属性的setter和getter当游戏代码尝试设置一个Text组件显示的内容时如myText.text “Hello World”;我们的Hook代码会被触发。我们截获这个“Hello World”字符串将其送入翻译流程然后将翻译后的“你好世界”设置回去。对于获取文本的操作我们可能需要返回翻译后的版本以保证游戏其他逻辑正常。TextMeshPro相关组件的文本设置方法现代Unity游戏大量使用TextMeshProTMP以获得更佳的字体渲染效果。TMP的文本设置路径与标准UI不同因此需要单独的Hook。XUnity通常也会针对TMP_Text类的相关方法进行拦截。这个过程依赖于一个叫做“Harmony”的库通常被BepInEx集成。Harmony允许你在运行时为目标方法打上“补丁”Patch分为前置Prefix、后置Postfix和绕行Transpiler等类型。XUnity主要使用后置补丁Postfix。例如在UI.Text.set_text方法执行之后我们的补丁方法被调用此时我们可以拿到游戏刚刚设置进去的原始字符串并进行替换。注意这种Hook是内存层面的只影响本次游戏进程。关闭游戏后所有修改都会消失游戏文件本身是完好无损的。这是一种非常“干净”的修改方式。2.2 翻译流程与缓存机制截获文本只是第一步。一个完整的翻译流程必须高效、稳定且能应对网络波动。XUnity设计了一个典型的“请求-缓存-回退”工作流。第一步文本规范化与哈希生成。并不是所有文本都需要翻译。像单个字母、数字、标点符号、游戏内部代码标识符如ITEM_123等直接跳过可以节省大量资源。对于需要翻译的文本工具会先对其进行修剪去除首尾空格然后计算一个哈希值如MD5或SHA1。这个哈希值将作为该文本的唯一标识用于后续的缓存查找。第二步多级缓存查找。为了最大化效率和减少对翻译API的调用很多API有调用次数或频率限制XUnity实现了至少两级缓存内存缓存Runtime Cache在本次游戏会话中已经翻译过的文本会存储在内存字典里。下次遇到相同文本直接返回结果速度极快。磁盘缓存Translation Cache游戏目录下会生成一个翻译缓存文件通常是Translation\文件夹下的.txt或.dat文件。这里存储了哈希值与翻译结果的映射。游戏启动时会加载这个文件。这样即使重启游戏之前翻译过的内容也无需再次联网请求实现了“一次翻译永久受益”。这也是为什么玩家社区可以分享彼此的缓存文件快速实现游戏汉化。第三步异步网络翻译请求。如果缓存未命中工具会启动一个异步任务将文本发送到配置好的翻译服务端点。这里有几个关键设计点异步操作翻译请求绝不能阻塞游戏的主线程否则会导致游戏卡顿甚至无响应。XUnity使用C#的async/await或类似的异步模式确保网络IO在后台进行。服务端抽象它支持配置多个翻译服务Google Bing DeepL等。这些服务被抽象为统一的接口ITranslator只需实现如何构造请求URL、解析返回的JSON或XML即可。超时与重试网络请求必须设置合理的超时时间如5-10秒并在失败时进行有限次数的重试。失败的翻译请求会被记录文本将保持原样显示避免因翻译服务不可用而导致游戏功能损坏。第四步文本替换与渲染。获取到翻译结果后工具需要将原始Text组件中的内容替换掉。这里不能简单地直接赋值因为游戏可能在后续帧中再次设置文本例如在对话中逐字显示。XUnity的常见做法是在Postfix补丁中将我们翻译好的字符串直接赋值给该Text组件的text属性。由于我们是在游戏逻辑设置完文本之后执行的我们的赋值会覆盖掉游戏设置的值从而显示在屏幕上。对于动态文本如不断变化的血量数字、倒计时需要特别小心。通常可以通过文本长度、是否包含变量格式如{0}等启发式规则来判断是否应该跳过翻译。3. 环境准备与工具部署实战理论讲完了我们动手把它装到游戏里。整个过程就像给游戏安装一个“辅助软件”需要一些耐心和细心。3.1 前置条件确认不是所有Unity游戏都能用XUnity自动翻译器。在开始前请确认以下几点游戏基于Unity引擎开发这是最基本的前提。通常可以通过查看游戏安装目录下是否有UnityPlayer.dll、GameAssembly.dll以及游戏名_Data\Managed\文件夹来判断。游戏使用Mono或IL2CPP脚本后端XUnity主要支持这两种。IL2CPP是Unity将C#代码编译成C再生成原生代码的 backend其Hook难度比Mono大但BepInEx和XUnity对其有专门的支持。你需要知道你的游戏是哪一种。一般来说较新的Unity游戏2018年后大量出现很可能使用IL2CPP以获得更好的性能和安全性。游戏未被强加密或混淆一些游戏会对程序集DLL进行加密或混淆这会使得Hook所需的类型和方法无法被正常定位导致插件加载失败。准备好合适的BepInEx版本这是整个插件的运行基础。BepInEx有不同的构建版本对应不同版本的Unity和不同的脚本后端。选错版本是导致插件失效的最常见原因。3.2 分步部署指南我们以一个典型的Windows平台Unity游戏为例假设游戏安装在D:\Games\MyUnityGame。步骤一获取BepInEx前往BepInEx的GitHub发布页。不要下载“Bleeding Edge”版本除非你明确需要最新特性。下载稳定版。根据你的游戏类型选择对于大多数Mono后端的旧游戏下载BepInEx_x64_5.4.21.0.zip版本号可能更新这样的通用包即可。对于IL2CPP后端的游戏你必须下载标有“BepInEx-unity.IL2CPP-win-x64”的专用版本。IL2CPP版本与Mono版本不通用将下载的ZIP包全部解压到游戏根目录即Game.exe所在的目录。解压后你会看到BepInEx文件夹、winhttp.dll、doorstop_config.ini等文件。步骤二首次运行并生成核心目录直接运行游戏的可执行文件如Game.exe。此时游戏可能会黑屏一段时间正常现象BepInEx正在初始化然后正常启动。进入游戏主菜单后直接退出游戏。再次查看游戏根目录你会发现BepInEx文件夹下生成了core、plugins等子目录。plugins文件夹就是我们后续放置XUnity插件的地方。步骤三获取并安装XUnity AutoTranslator从GitHub或可靠的Mod发布站如Nexus Mods下载XUnity AutoTranslator的最新版本。通常文件名类似XUnity.AutoTranslator-BepInEx-5.4.21.0.zip。将其解压你会看到里面也有一个BepInEx文件夹。将这个下载的BepInEx文件夹合并到游戏根目录的BepInEx文件夹中。通常只需要复制plugins和patchers如果有里的内容到游戏目录对应的位置。务必确保文件结构正确。一个常见的正确结构是游戏根目录\BepInEx\plugins\XUnity.AutoTranslator\AutoTranslator.dll。步骤四配置翻译引擎启动游戏然后退出。XUnity插件会在BepInEx\config文件夹下生成它的配置文件AutoTranslatorConfig.ini。用记事本或其他文本编辑器打开这个配置文件。找到[Service]部分。你会看到类似GoogleTranslate、BaiduTranslate、DeepL等选项。默认可能启用的是Google。你需要根据你的网络环境选择一个可用的服务。谷歌翻译免费但需网络环境直接设置Enabledtrue即可。但需要注意免费的谷歌翻译API可能有频率限制。百度翻译需API密钥你需要注册百度翻译开放平台创建一个通用翻译服务获得AppID和密钥。然后在配置中设置[Baidu] Enabledtrue AppId你的AppId Secret你的密钥DeepL质量高但收费需要付费API密钥。你还可以在[General]部分设置目标语言例如Languagezh表示翻译为简体中文。步骤五测试与验证重新启动游戏。如果一切顺利在游戏启动时BepInEx的控制台窗口如果配置了或游戏根目录下的LogOutput.log文件中会看到XUnity AutoTranslator加载成功的日志信息。进入游戏找到有文字的地方如主菜单、物品描述。第一次遇到新文本时会有短暂的延迟正在联网翻译随后文本应该会被替换成中文。翻译过的文本会被自动保存到BepInEx\Translation文件夹下的缓存文件中。实操心得部署失败十有八九是BepInEx版本不对。一个快速判断游戏是Mono还是IL2CPP的方法是查看游戏目录下游戏名_Data\Managed\文件夹。如果里面有很多.dll文件很可能是Mono。如果只有Metadata文件夹和global-metadata.dat等文件没有或极少有.dll那基本就是IL2CPP。对于IL2CPP游戏务必使用IL2CPP版本的BepInEx这是铁律。4. 高级配置与性能调优安装成功只是开始。要让翻译体验更上一层楼避免游戏卡顿、翻译错乱等问题你需要深入了解配置文件的各个选项。4.1 核心配置文件详解AutoTranslatorConfig.ini文件是控制插件行为的中枢。我们来剖析几个关键区块[General]通用设置Languagezh: 目标语言代码。zh是简体中文zh-TW是繁体中文ja是日文依此类推。MaxCharactersPerTranslation500: 单次发送翻译的最大字符数。有些翻译API有长度限制超长的文本如一整页书籍内容会被自动分割发送。调低此值可以避免API拒绝请求但会增加请求次数。DelayBetweenTranslations50: 两次翻译请求之间的最小延迟毫秒。这是防止被翻译服务限流的关键参数。免费API尤其需要设置一个合理的值如200-500ms不要设为0。SkipAlreadyTranslatedTexttrue: 是否跳过缓存中已有的翻译。通常保持开启以提升性能。[Service]服务选择与回退[Service] ; 启用的服务按顺序尝试 EnabledGoogleTranslate,BaiduTranslate这里定义了插件将按顺序尝试的翻译服务。如果Google翻译失败超时或返回错误它会自动尝试百度翻译。你可以根据自己的情况调整顺序和启用的服务。[Behaviour]翻译行为控制EnableTranslationtrue: 总开关。设为false可以临时关闭所有翻译。EnableSubtitlefalse: 是否启用字幕模式。开启后翻译文本会以字幕形式显示在屏幕下方而不替换原文本。适合用于学习外语。OverrideFont: 可以指定一个字体文件名需放入BepInEx\Translation文件夹强制游戏使用该字体显示翻译文本解决某些游戏字体缺失导致的显示方框问题。TextGetterCompatibilityModefalse: 文本获取兼容模式。某些游戏获取文本的方式特殊开启此模式可能解决翻译不显示的问题但可能影响性能。[Speech]语音翻译实验性部分版本的XUnity支持通过在线TTS文本转语音服务朗读翻译后的文本。这属于高级功能配置复杂且对网络要求高普通用户建议保持关闭。4.2 性能调优与问题规避实时翻译是一个对性能敏感的操作不当配置会导致游戏卡顿、翻译延迟甚至崩溃。控制翻译频率与延迟DelayBetweenTranslations是你的好朋友。对于免费API强烈建议设置为300毫秒或以上。这意味着一秒钟最多翻译3-4句文本对于大多数游戏对话节奏来说足够了能极大降低被API封禁的风险。在[Regex]配置节你可以添加规则来排除不需要翻译的文本。例如排除所有纯数字、排除包含特定前缀如MSG_的文本。这能减少不必要的翻译请求。[Regex] ; 排除纯数字 ^\d$ ; 排除以“TMP_”开头的内部标识符 ^TMP_.*管理缓存文件翻译缓存文件*.dat会随着游戏时间增长而变大。定期清理或备份旧的缓存文件是良好的习惯。你可以手动编辑Text文件夹下的*.txt文件来修正错误的翻译。找到对应的原文行修改其后的翻译文本即可。下次游戏加载时会优先使用你手动修正的版本。处理特殊UI框架一些游戏使用非常规的UI系统如NGUI、uGUI的复杂变种或自定义文本渲染。XUnity可能无法自动Hook到。这时需要查看日志文件找到未被翻译的文本对应的组件类型然后通过配置[UnityUI]或[TextMeshPro]下的ComponentBlacklist黑名单或ComponentWhitelist白名单进行微调或者等待插件更新对该游戏的特殊支持。内存与日志监控开启BepInEx的控制台窗口在BepInEx.cfg中配置Logging.Console.Enabled true可以实时看到翻译请求和错误信息便于调试。如果游戏出现明显卡顿观察控制台输出是否在密集地进行网络请求。如果是请调大DelayBetweenTranslations。5. 疑难杂症排查与社区资源利用即使按照指南操作你也可能会遇到各种奇怪的问题。这里我整理了一份常见问题速查表涵盖了从安装到使用的大部分坑。问题现象可能原因排查步骤与解决方案游戏启动崩溃或无响应1. BepInEx版本与游戏不兼容尤其是IL2CPP游戏用了Mono版。2. 游戏反作弊系统如EasyAntiCheat阻止注入。3. 与其他Mod冲突。1.首要检查确认游戏脚本后端下载对应版本的BepInEx。2. 查看游戏根目录下LogOutput.log或BepInEx/LogOutput.log文件看崩溃前最后几条错误信息。3. 尝试纯净环境只装BepInEx和XUnity测试。4. 对于有反作弊的在线游戏强烈不建议使用任何注入式Mod可能导致封号。插件成功加载但游戏内无任何翻译1. 翻译服务未正确配置或不可用。2. Hook的目标组件类型不对。3. 文本被游戏以特殊方式渲染如图片、自定义Shader。1. 检查AutoTranslatorConfig.ini确保[Service]下至少有一个服务Enabledtrue且配置正确如API密钥。2. 打开BepInEx控制台观察是否有“Translating: XXX”的日志输出。如果没有说明文本未被捕获。3. 尝试在配置中启用[Behaviour]下的TextGetterCompatibilityMode。4. 检查游戏是否使用TextMeshPro。确保你安装的XUnity版本支持TMP。翻译延迟极高或经常失败1. 网络连接问题。2. 翻译API限流或配额用尽。3.DelayBetweenTranslations设置过小触发频率限制。1. 检查网络连通性。尝试ping翻译服务域名。2. 如果是付费API检查后台用量和配额。3.立即增大DelayBetweenTranslations值建议先调到10001秒测试。4. 在配置中启用备用翻译服务形成故障转移。部分文本翻译了部分没翻译1. 文本被游戏动态拼接。2. 文本包含特殊格式或富文本标签如colorred。3. 该文本属于黑名单或正则排除规则。1. 查看未翻译文本的规律。如果是“Attack 10”这种可能是“Attack”和“10”分开渲染的无法整体翻译。2. XUnity默认会尝试剥离富文本标签再翻译但复杂情况可能处理不了。可以尝试在配置中调整[Behaviour]下的TextProcessing相关选项。3. 检查[Regex]配置节看是否有过于宽泛的排除规则。翻译结果显示为方框“□□□”游戏字体缺少中文字形支持。1. 在[Behaviour]中设置OverrideFont指定一个包含中文的字体文件如msyh.ttc微软雅黑并放入BepInEx\Translation文件夹。2. 这是一个比较进阶的解决方案需要找到合适的字体并测试。BepInEx控制台不显示未启用控制台日志。编辑BepInEx.cfg文件找到[Logging.Console]部分设置Enabled true。重启游戏。社区资源利用 当你遇到无法解决的问题时别忘了利用社区力量。GitHub Issues前往XUnity AutoTranslator的GitHub仓库在Issues里搜索你遇到的问题。很可能已经有人提出并解决了。游戏特定的Mod社区对于热门游戏Nexus Mods、贴吧、专门的Discord频道里常有玩家分享针对该游戏优化过的XUnity配置文件、字体文件甚至完整的翻译缓存。使用这些资源可以免去大量配置和翻译等待时间。日志文件是金钥匙BepInEx/LogOutput.log文件包含了最详细的加载、Hook、翻译过程信息。遇到问题第一件事就是打开它搜索“Error”、“Warning”、“Exception”等关键词通常能直接定位问题根源。6. 从使用者到贡献者理解插件架构与扩展如果你不满足于只是使用还想定制功能甚至为某个特定游戏贡献代码那么你需要深入其代码架构。XUnity AutoTranslator是一个设计良好的插件其核心模块清晰分离。核心模块解析引导与配置模块Bootstrapper负责在BepInEx启动时加载本插件读取配置文件初始化全局翻译器Translator实例。Hook/补丁模块Patchers利用Harmony库在游戏启动早期对UI.Text、TextMeshPro等关键类的方法进行打补丁。这些补丁方法是翻译流程的“触发器”。翻译引擎模块Translators定义了ITranslator接口并有GoogleTranslator、BaiduTranslator等具体实现。负责与外部翻译API通信处理请求和响应。资源管理与缓存模块Resource Managers管理内存缓存和磁盘缓存。负责加载、保存翻译缓存文件.dat以及处理字体等外部资源。文本处理管道Text Processing Pipeline这是翻译前的预处理和后处理环节。包括文本规范化、正则过滤、分句、富文本标签剥离与还原等。你可以在这里添加自定义的文本处理规则。如何为特定游戏添加支持有些游戏使用了极其冷门的UI插件导致标准Hook失效。这时就需要编写“游戏特定补丁”Game-Specific Patch。定位目标方法使用dnSpy、ILSpy等反编译工具打开游戏的程序集Assembly-CSharp.dll等找到负责最终文本显示的那个组件的set_text或类似方法。编写Harmony补丁创建一个新的BepInEx插件项目引用Harmony和XUnity.AutoTranslator的API如果暴露。编写一个Postfix补丁在该游戏特有的文本设置方法中调用XUnity提供的公共翻译接口如AutoTranslator.DefaultInstance.TranslateAsync来获取并替换文本。设置加载时机确保你的补丁在XUnity核心插件加载之后执行并且只针对该特定游戏生效可以通过检查游戏进程名或版本号来实现。这个过程需要对C#、.NET反编译和Harmony库有较深的理解属于高级Mod开发范畴。但对于解决“硬骨头”游戏的中文化问题这是唯一途径。我个人在实际折腾了十几个游戏后的体会是XUnity AutoTranslator的稳定性和成功率大概在80%左右。对于标准uGUI/TextMeshPro的游戏它几乎开箱即用。它的价值不仅仅在于提供了一个工具更在于它展示了一种“非侵入式”的游戏内容修改范式。通过Hook和缓存它优雅地解决了动态翻译的难题。对于开发者这份源代码是学习运行时修改、插件系统设计、异步编程和网络集成的绝佳材料。最后一个小技巧如果你经常折腾不同游戏的翻译不妨在电脑上建立一个统一的BepInEx和XUnity.AutoTranslator的版本库并为你玩的每个游戏单独备份其Translation缓存文件夹。这样在新游戏出来时你可以快速部署一套干净的测试环境而不会影响其他已经配置好的游戏。 Unity游戏实时翻译插件XUnity AutoTranslator：原理、部署与实战调优
1. 项目概述为什么我们需要为Unity游戏实现实时翻译如果你是一个喜欢玩各种独立游戏或者小众Unity游戏的玩家或者你本身就是一个Unity开发者那么“语言不通”这个问题你一定深有体会。很多优秀的游戏尤其是那些由小型团队或个人开发者制作的往往首发只有英文或日文版本。等一个官方的中文补丁可能遥遥无期。这时候一个能在游戏运行时实时将屏幕上的外文文本替换成中文的工具就成了“救星”。XUnity AutoTranslator通常被简称为XUnity自动翻译器就是这样一个在玩家社区中广为流传的神器。简单来说它是一个基于BepInEx插件框架的Unity游戏Mod模组。它的核心功能是“劫持”游戏在屏幕上绘制文本的调用将原始文本比如英文发送到指定的在线翻译服务如谷歌翻译、百度翻译、DeepL等获取翻译结果后再将其渲染到屏幕上从而实现近乎实时的游戏内文本翻译。这听起来有点像“外挂”但它不修改游戏逻辑只干预文本渲染流程目的纯粹是为了消除语言障碍。这个工具的价值远不止于“玩家爽玩”。对于开发者而言它提供了一个极佳的研究样本你可以通过它学习Unity的文本渲染管线、IL代码注入Hook技术、异步网络请求在游戏中的处理以及如何设计一个灵活、可配置的插件架构。无论你是想为自己的游戏快速制作一个多语言原型还是想深入理解Unity Mod开发这个项目都是一个绝佳的切入点。接下来我将以一个资深Mod开发者和Unity技术爱好者的视角带你彻底拆解XUnity AutoTranslator的实现原理、部署方法、核心配置以及那些官方文档里不会写的“踩坑”实录。2. 核心原理深度拆解文本是如何被“劫持”并替换的要理解XUnity自动翻译器如何工作我们需要深入到Unity引擎的运行时层面。Unity游戏中的文本显示绝大多数情况下是通过UnityEngine.UI.Text组件或TextMeshPro组件来完成的。这些组件在每帧更新时会将其text属性的内容提交给底层的渲染系统进行绘制。2.1 Hook技术在关键位置“插入”我们的逻辑XUnity自动翻译器的核心手段是“Hook”钩子或者更专业地说是“方法拦截”。它并不直接修改游戏的原生DLL文件而是在游戏运行时通过BepInEx框架提供的强大能力将我们自己的代码“注入”到游戏进程的关键函数调用中。具体到文本翻译它主要Hook了两个地方UI.Text组件的text属性的setter和getter当游戏代码尝试设置一个Text组件显示的内容时如myText.text “Hello World”;我们的Hook代码会被触发。我们截获这个“Hello World”字符串将其送入翻译流程然后将翻译后的“你好世界”设置回去。对于获取文本的操作我们可能需要返回翻译后的版本以保证游戏其他逻辑正常。TextMeshPro相关组件的文本设置方法现代Unity游戏大量使用TextMeshProTMP以获得更佳的字体渲染效果。TMP的文本设置路径与标准UI不同因此需要单独的Hook。XUnity通常也会针对TMP_Text类的相关方法进行拦截。这个过程依赖于一个叫做“Harmony”的库通常被BepInEx集成。Harmony允许你在运行时为目标方法打上“补丁”Patch分为前置Prefix、后置Postfix和绕行Transpiler等类型。XUnity主要使用后置补丁Postfix。例如在UI.Text.set_text方法执行之后我们的补丁方法被调用此时我们可以拿到游戏刚刚设置进去的原始字符串并进行替换。注意这种Hook是内存层面的只影响本次游戏进程。关闭游戏后所有修改都会消失游戏文件本身是完好无损的。这是一种非常“干净”的修改方式。2.2 翻译流程与缓存机制截获文本只是第一步。一个完整的翻译流程必须高效、稳定且能应对网络波动。XUnity设计了一个典型的“请求-缓存-回退”工作流。第一步文本规范化与哈希生成。并不是所有文本都需要翻译。像单个字母、数字、标点符号、游戏内部代码标识符如ITEM_123等直接跳过可以节省大量资源。对于需要翻译的文本工具会先对其进行修剪去除首尾空格然后计算一个哈希值如MD5或SHA1。这个哈希值将作为该文本的唯一标识用于后续的缓存查找。第二步多级缓存查找。为了最大化效率和减少对翻译API的调用很多API有调用次数或频率限制XUnity实现了至少两级缓存内存缓存Runtime Cache在本次游戏会话中已经翻译过的文本会存储在内存字典里。下次遇到相同文本直接返回结果速度极快。磁盘缓存Translation Cache游戏目录下会生成一个翻译缓存文件通常是Translation\文件夹下的.txt或.dat文件。这里存储了哈希值与翻译结果的映射。游戏启动时会加载这个文件。这样即使重启游戏之前翻译过的内容也无需再次联网请求实现了“一次翻译永久受益”。这也是为什么玩家社区可以分享彼此的缓存文件快速实现游戏汉化。第三步异步网络翻译请求。如果缓存未命中工具会启动一个异步任务将文本发送到配置好的翻译服务端点。这里有几个关键设计点异步操作翻译请求绝不能阻塞游戏的主线程否则会导致游戏卡顿甚至无响应。XUnity使用C#的async/await或类似的异步模式确保网络IO在后台进行。服务端抽象它支持配置多个翻译服务Google Bing DeepL等。这些服务被抽象为统一的接口ITranslator只需实现如何构造请求URL、解析返回的JSON或XML即可。超时与重试网络请求必须设置合理的超时时间如5-10秒并在失败时进行有限次数的重试。失败的翻译请求会被记录文本将保持原样显示避免因翻译服务不可用而导致游戏功能损坏。第四步文本替换与渲染。获取到翻译结果后工具需要将原始Text组件中的内容替换掉。这里不能简单地直接赋值因为游戏可能在后续帧中再次设置文本例如在对话中逐字显示。XUnity的常见做法是在Postfix补丁中将我们翻译好的字符串直接赋值给该Text组件的text属性。由于我们是在游戏逻辑设置完文本之后执行的我们的赋值会覆盖掉游戏设置的值从而显示在屏幕上。对于动态文本如不断变化的血量数字、倒计时需要特别小心。通常可以通过文本长度、是否包含变量格式如{0}等启发式规则来判断是否应该跳过翻译。3. 环境准备与工具部署实战理论讲完了我们动手把它装到游戏里。整个过程就像给游戏安装一个“辅助软件”需要一些耐心和细心。3.1 前置条件确认不是所有Unity游戏都能用XUnity自动翻译器。在开始前请确认以下几点游戏基于Unity引擎开发这是最基本的前提。通常可以通过查看游戏安装目录下是否有UnityPlayer.dll、GameAssembly.dll以及游戏名_Data\Managed\文件夹来判断。游戏使用Mono或IL2CPP脚本后端XUnity主要支持这两种。IL2CPP是Unity将C#代码编译成C再生成原生代码的 backend其Hook难度比Mono大但BepInEx和XUnity对其有专门的支持。你需要知道你的游戏是哪一种。一般来说较新的Unity游戏2018年后大量出现很可能使用IL2CPP以获得更好的性能和安全性。游戏未被强加密或混淆一些游戏会对程序集DLL进行加密或混淆这会使得Hook所需的类型和方法无法被正常定位导致插件加载失败。准备好合适的BepInEx版本这是整个插件的运行基础。BepInEx有不同的构建版本对应不同版本的Unity和不同的脚本后端。选错版本是导致插件失效的最常见原因。3.2 分步部署指南我们以一个典型的Windows平台Unity游戏为例假设游戏安装在D:\Games\MyUnityGame。步骤一获取BepInEx前往BepInEx的GitHub发布页。不要下载“Bleeding Edge”版本除非你明确需要最新特性。下载稳定版。根据你的游戏类型选择对于大多数Mono后端的旧游戏下载BepInEx_x64_5.4.21.0.zip版本号可能更新这样的通用包即可。对于IL2CPP后端的游戏你必须下载标有“BepInEx-unity.IL2CPP-win-x64”的专用版本。IL2CPP版本与Mono版本不通用将下载的ZIP包全部解压到游戏根目录即Game.exe所在的目录。解压后你会看到BepInEx文件夹、winhttp.dll、doorstop_config.ini等文件。步骤二首次运行并生成核心目录直接运行游戏的可执行文件如Game.exe。此时游戏可能会黑屏一段时间正常现象BepInEx正在初始化然后正常启动。进入游戏主菜单后直接退出游戏。再次查看游戏根目录你会发现BepInEx文件夹下生成了core、plugins等子目录。plugins文件夹就是我们后续放置XUnity插件的地方。步骤三获取并安装XUnity AutoTranslator从GitHub或可靠的Mod发布站如Nexus Mods下载XUnity AutoTranslator的最新版本。通常文件名类似XUnity.AutoTranslator-BepInEx-5.4.21.0.zip。将其解压你会看到里面也有一个BepInEx文件夹。将这个下载的BepInEx文件夹合并到游戏根目录的BepInEx文件夹中。通常只需要复制plugins和patchers如果有里的内容到游戏目录对应的位置。务必确保文件结构正确。一个常见的正确结构是游戏根目录\BepInEx\plugins\XUnity.AutoTranslator\AutoTranslator.dll。步骤四配置翻译引擎启动游戏然后退出。XUnity插件会在BepInEx\config文件夹下生成它的配置文件AutoTranslatorConfig.ini。用记事本或其他文本编辑器打开这个配置文件。找到[Service]部分。你会看到类似GoogleTranslate、BaiduTranslate、DeepL等选项。默认可能启用的是Google。你需要根据你的网络环境选择一个可用的服务。谷歌翻译免费但需网络环境直接设置Enabledtrue即可。但需要注意免费的谷歌翻译API可能有频率限制。百度翻译需API密钥你需要注册百度翻译开放平台创建一个通用翻译服务获得AppID和密钥。然后在配置中设置[Baidu] Enabledtrue AppId你的AppId Secret你的密钥DeepL质量高但收费需要付费API密钥。你还可以在[General]部分设置目标语言例如Languagezh表示翻译为简体中文。步骤五测试与验证重新启动游戏。如果一切顺利在游戏启动时BepInEx的控制台窗口如果配置了或游戏根目录下的LogOutput.log文件中会看到XUnity AutoTranslator加载成功的日志信息。进入游戏找到有文字的地方如主菜单、物品描述。第一次遇到新文本时会有短暂的延迟正在联网翻译随后文本应该会被替换成中文。翻译过的文本会被自动保存到BepInEx\Translation文件夹下的缓存文件中。实操心得部署失败十有八九是BepInEx版本不对。一个快速判断游戏是Mono还是IL2CPP的方法是查看游戏目录下游戏名_Data\Managed\文件夹。如果里面有很多.dll文件很可能是Mono。如果只有Metadata文件夹和global-metadata.dat等文件没有或极少有.dll那基本就是IL2CPP。对于IL2CPP游戏务必使用IL2CPP版本的BepInEx这是铁律。4. 高级配置与性能调优安装成功只是开始。要让翻译体验更上一层楼避免游戏卡顿、翻译错乱等问题你需要深入了解配置文件的各个选项。4.1 核心配置文件详解AutoTranslatorConfig.ini文件是控制插件行为的中枢。我们来剖析几个关键区块[General]通用设置Languagezh: 目标语言代码。zh是简体中文zh-TW是繁体中文ja是日文依此类推。MaxCharactersPerTranslation500: 单次发送翻译的最大字符数。有些翻译API有长度限制超长的文本如一整页书籍内容会被自动分割发送。调低此值可以避免API拒绝请求但会增加请求次数。DelayBetweenTranslations50: 两次翻译请求之间的最小延迟毫秒。这是防止被翻译服务限流的关键参数。免费API尤其需要设置一个合理的值如200-500ms不要设为0。SkipAlreadyTranslatedTexttrue: 是否跳过缓存中已有的翻译。通常保持开启以提升性能。[Service]服务选择与回退[Service] ; 启用的服务按顺序尝试 EnabledGoogleTranslate,BaiduTranslate这里定义了插件将按顺序尝试的翻译服务。如果Google翻译失败超时或返回错误它会自动尝试百度翻译。你可以根据自己的情况调整顺序和启用的服务。[Behaviour]翻译行为控制EnableTranslationtrue: 总开关。设为false可以临时关闭所有翻译。EnableSubtitlefalse: 是否启用字幕模式。开启后翻译文本会以字幕形式显示在屏幕下方而不替换原文本。适合用于学习外语。OverrideFont: 可以指定一个字体文件名需放入BepInEx\Translation文件夹强制游戏使用该字体显示翻译文本解决某些游戏字体缺失导致的显示方框问题。TextGetterCompatibilityModefalse: 文本获取兼容模式。某些游戏获取文本的方式特殊开启此模式可能解决翻译不显示的问题但可能影响性能。[Speech]语音翻译实验性部分版本的XUnity支持通过在线TTS文本转语音服务朗读翻译后的文本。这属于高级功能配置复杂且对网络要求高普通用户建议保持关闭。4.2 性能调优与问题规避实时翻译是一个对性能敏感的操作不当配置会导致游戏卡顿、翻译延迟甚至崩溃。控制翻译频率与延迟DelayBetweenTranslations是你的好朋友。对于免费API强烈建议设置为300毫秒或以上。这意味着一秒钟最多翻译3-4句文本对于大多数游戏对话节奏来说足够了能极大降低被API封禁的风险。在[Regex]配置节你可以添加规则来排除不需要翻译的文本。例如排除所有纯数字、排除包含特定前缀如MSG_的文本。这能减少不必要的翻译请求。[Regex] ; 排除纯数字 ^\d$ ; 排除以“TMP_”开头的内部标识符 ^TMP_.*管理缓存文件翻译缓存文件*.dat会随着游戏时间增长而变大。定期清理或备份旧的缓存文件是良好的习惯。你可以手动编辑Text文件夹下的*.txt文件来修正错误的翻译。找到对应的原文行修改其后的翻译文本即可。下次游戏加载时会优先使用你手动修正的版本。处理特殊UI框架一些游戏使用非常规的UI系统如NGUI、uGUI的复杂变种或自定义文本渲染。XUnity可能无法自动Hook到。这时需要查看日志文件找到未被翻译的文本对应的组件类型然后通过配置[UnityUI]或[TextMeshPro]下的ComponentBlacklist黑名单或ComponentWhitelist白名单进行微调或者等待插件更新对该游戏的特殊支持。内存与日志监控开启BepInEx的控制台窗口在BepInEx.cfg中配置Logging.Console.Enabled true可以实时看到翻译请求和错误信息便于调试。如果游戏出现明显卡顿观察控制台输出是否在密集地进行网络请求。如果是请调大DelayBetweenTranslations。5. 疑难杂症排查与社区资源利用即使按照指南操作你也可能会遇到各种奇怪的问题。这里我整理了一份常见问题速查表涵盖了从安装到使用的大部分坑。问题现象可能原因排查步骤与解决方案游戏启动崩溃或无响应1. BepInEx版本与游戏不兼容尤其是IL2CPP游戏用了Mono版。2. 游戏反作弊系统如EasyAntiCheat阻止注入。3. 与其他Mod冲突。1.首要检查确认游戏脚本后端下载对应版本的BepInEx。2. 查看游戏根目录下LogOutput.log或BepInEx/LogOutput.log文件看崩溃前最后几条错误信息。3. 尝试纯净环境只装BepInEx和XUnity测试。4. 对于有反作弊的在线游戏强烈不建议使用任何注入式Mod可能导致封号。插件成功加载但游戏内无任何翻译1. 翻译服务未正确配置或不可用。2. Hook的目标组件类型不对。3. 文本被游戏以特殊方式渲染如图片、自定义Shader。1. 检查AutoTranslatorConfig.ini确保[Service]下至少有一个服务Enabledtrue且配置正确如API密钥。2. 打开BepInEx控制台观察是否有“Translating: XXX”的日志输出。如果没有说明文本未被捕获。3. 尝试在配置中启用[Behaviour]下的TextGetterCompatibilityMode。4. 检查游戏是否使用TextMeshPro。确保你安装的XUnity版本支持TMP。翻译延迟极高或经常失败1. 网络连接问题。2. 翻译API限流或配额用尽。3.DelayBetweenTranslations设置过小触发频率限制。1. 检查网络连通性。尝试ping翻译服务域名。2. 如果是付费API检查后台用量和配额。3.立即增大DelayBetweenTranslations值建议先调到10001秒测试。4. 在配置中启用备用翻译服务形成故障转移。部分文本翻译了部分没翻译1. 文本被游戏动态拼接。2. 文本包含特殊格式或富文本标签如colorred。3. 该文本属于黑名单或正则排除规则。1. 查看未翻译文本的规律。如果是“Attack 10”这种可能是“Attack”和“10”分开渲染的无法整体翻译。2. XUnity默认会尝试剥离富文本标签再翻译但复杂情况可能处理不了。可以尝试在配置中调整[Behaviour]下的TextProcessing相关选项。3. 检查[Regex]配置节看是否有过于宽泛的排除规则。翻译结果显示为方框“□□□”游戏字体缺少中文字形支持。1. 在[Behaviour]中设置OverrideFont指定一个包含中文的字体文件如msyh.ttc微软雅黑并放入BepInEx\Translation文件夹。2. 这是一个比较进阶的解决方案需要找到合适的字体并测试。BepInEx控制台不显示未启用控制台日志。编辑BepInEx.cfg文件找到[Logging.Console]部分设置Enabled true。重启游戏。社区资源利用 当你遇到无法解决的问题时别忘了利用社区力量。GitHub Issues前往XUnity AutoTranslator的GitHub仓库在Issues里搜索你遇到的问题。很可能已经有人提出并解决了。游戏特定的Mod社区对于热门游戏Nexus Mods、贴吧、专门的Discord频道里常有玩家分享针对该游戏优化过的XUnity配置文件、字体文件甚至完整的翻译缓存。使用这些资源可以免去大量配置和翻译等待时间。日志文件是金钥匙BepInEx/LogOutput.log文件包含了最详细的加载、Hook、翻译过程信息。遇到问题第一件事就是打开它搜索“Error”、“Warning”、“Exception”等关键词通常能直接定位问题根源。6. 从使用者到贡献者理解插件架构与扩展如果你不满足于只是使用还想定制功能甚至为某个特定游戏贡献代码那么你需要深入其代码架构。XUnity AutoTranslator是一个设计良好的插件其核心模块清晰分离。核心模块解析引导与配置模块Bootstrapper负责在BepInEx启动时加载本插件读取配置文件初始化全局翻译器Translator实例。Hook/补丁模块Patchers利用Harmony库在游戏启动早期对UI.Text、TextMeshPro等关键类的方法进行打补丁。这些补丁方法是翻译流程的“触发器”。翻译引擎模块Translators定义了ITranslator接口并有GoogleTranslator、BaiduTranslator等具体实现。负责与外部翻译API通信处理请求和响应。资源管理与缓存模块Resource Managers管理内存缓存和磁盘缓存。负责加载、保存翻译缓存文件.dat以及处理字体等外部资源。文本处理管道Text Processing Pipeline这是翻译前的预处理和后处理环节。包括文本规范化、正则过滤、分句、富文本标签剥离与还原等。你可以在这里添加自定义的文本处理规则。如何为特定游戏添加支持有些游戏使用了极其冷门的UI插件导致标准Hook失效。这时就需要编写“游戏特定补丁”Game-Specific Patch。定位目标方法使用dnSpy、ILSpy等反编译工具打开游戏的程序集Assembly-CSharp.dll等找到负责最终文本显示的那个组件的set_text或类似方法。编写Harmony补丁创建一个新的BepInEx插件项目引用Harmony和XUnity.AutoTranslator的API如果暴露。编写一个Postfix补丁在该游戏特有的文本设置方法中调用XUnity提供的公共翻译接口如AutoTranslator.DefaultInstance.TranslateAsync来获取并替换文本。设置加载时机确保你的补丁在XUnity核心插件加载之后执行并且只针对该特定游戏生效可以通过检查游戏进程名或版本号来实现。这个过程需要对C#、.NET反编译和Harmony库有较深的理解属于高级Mod开发范畴。但对于解决“硬骨头”游戏的中文化问题这是唯一途径。我个人在实际折腾了十几个游戏后的体会是XUnity AutoTranslator的稳定性和成功率大概在80%左右。对于标准uGUI/TextMeshPro的游戏它几乎开箱即用。它的价值不仅仅在于提供了一个工具更在于它展示了一种“非侵入式”的游戏内容修改范式。通过Hook和缓存它优雅地解决了动态翻译的难题。对于开发者这份源代码是学习运行时修改、插件系统设计、异步编程和网络集成的绝佳材料。最后一个小技巧如果你经常折腾不同游戏的翻译不妨在电脑上建立一个统一的BepInEx和XUnity.AutoTranslator的版本库并为你玩的每个游戏单独备份其Translation缓存文件夹。这样在新游戏出来时你可以快速部署一套干净的测试环境而不会影响其他已经配置好的游戏。