1. 项目概述为什么你需要XUnity.AutoTranslator如果你是一名Unity游戏的玩家尤其是那些只有日文、英文等外语版本的小众独立游戏或视觉小说爱好者你一定经历过这样的痛苦面对屏幕上大段的剧情文本只能一边查词典一边连蒙带猜游戏体验大打折扣。或者你是一名游戏Modder想为你喜爱的游戏制作汉化补丁但面对游戏引擎内部复杂的资源结构和文本调用方式感到无从下手。XUnity.AutoTranslator以下简称AutoTranslator的出现就是为了解决这个核心痛点。它不是一个简单的屏幕OCR翻译工具而是一个深度集成到Unity引擎运行时、能够直接拦截并替换游戏内文本资源的强大插件。简单来说它能让游戏在显示文本的瞬间自动将其替换为你指定的翻译无论是通过在线翻译API如谷歌、百度、DeepL实时翻译还是加载你预先准备好的翻译文件。这个项目的价值远不止“玩游戏更方便”。对于Mod社区而言它降低了为Unity游戏制作本地化补丁的技术门槛。你不再需要反编译游戏程序集、破解资源包格式只需通过AutoTranslator提供的机制就能实现文本、甚至图片资源的替换。对于开发者它也是一个极佳的参考展示了如何通过Hook和资源重定向技术在运行时动态修改Unity应用的行为。2. 核心原理与架构拆解它到底是怎么工作的要理解AutoTranslator的强大之处我们需要深入其内部工作机制。它本质上是一个运行在游戏进程内的“中间人”Man-in-the-Middle在游戏引擎Unity试图渲染文本到屏幕的路径上插入自己的处理逻辑。2.1 核心拦截机制Hook与资源重定向AutoTranslator的核心依赖于两个关键技术方法钩子Hook和资源重定向Resource Redirection。方法钩子Hook游戏内所有的文本最终都需要通过Unity的UI组件如UnityEngine.UI.Text、TextMeshPro等的text属性来设置。AutoTranslator利用Harmony或MonoMod等库在游戏启动时将这些设置文本的方法“钩住”。当游戏调用someTextComponent.text “こんにちは”时控制权会先转移到AutoTranslator的代码中。此时插件会检查是否有对应的翻译无论是来自缓存文件还是在线API如果有则将其替换为“你好”然后再将修改后的文本设置回UI组件。对于玩家而言这个过程是瞬间完成的感觉就像游戏原生支持中文一样。资源重定向Resource Redirection有些游戏的文本并非动态设置而是直接存储在资源文件如.assets、AssetBundle中。对于这种情况方法钩子可能无法触及。AutoTranslator的Resource Redirector模块则更底层它拦截了Unity加载资源如Resources.Load,AssetBundle.LoadAsset的调用。当游戏尝试加载一个文本资源TextAsset时Resource Redirector可以将其“重定向”到插件指定的目录下的一个修改过的文件。这意味着你可以直接替换游戏原始的脚本文件、对话文件等实现更彻底、更稳定的翻译。2.2 工作流程与数据流一个典型的翻译请求在AutoTranslator内部会经历以下流程文本捕获游戏尝试更新UI文本被Hook拦截。插件获取到原始字符串如“Item acquired!”。预处理对原始字符串进行清理比如去除首尾空白字符、处理特殊换行符等。这一步是为了提高翻译匹配的准确性和缓存命中率。缓存查询插件首先在本地翻译缓存文件通常是Translation\{Lang}\Text\_AutoGeneratedTranslations.txt中查找是否有该字符串的现成翻译。如果有直接使用极大提升响应速度并减少网络请求。在线翻译如缓存未命中如果缓存中没有且用户配置了在线翻译端点如Google Translate插件会将预处理后的文本发送到对应的翻译API。后处理收到翻译结果后可能需要进行后处理比如调整标点符号、处理因翻译导致的文本长度变化这可能会触发UI自动重排。应用与缓存将处理后的翻译文本设置回UI组件同时将“原文-译文”对写入缓存文件供下次使用。资源重定向并行路径对于通过资源加载的文本Resource Redirector会在加载时直接返回已翻译的文本资源文件游戏代码感知不到任何变化。这种双管齐下的方式运行时Hook 资源预替换使得AutoTranslator能够应对绝大多数Unity游戏的文本翻译需求。3. 实战部署从零开始配置你的第一个游戏翻译理论讲完我们进入实战环节。假设我们要为一款名为“MyFantasyGame.exe”的Unity游戏添加中文翻译。3.1 环境准备与插件安装首先你需要确定游戏使用的插件框架。AutoTranslator支持多种主流Unity Mod框架BepInEx目前最流行的框架适用于大多数使用Mono后端编译的Unity游戏。MelonLoader另一款常用框架常见于较新的游戏。IPA主要用于特定平台的游戏。以BepInEx为例安装步骤如下安装BepInEx从BepInEx的GitHub发布页下载对应版本通常是一个压缩包。将其解压到游戏根目录即MyFantasyGame.exe所在的文件夹。运行一次游戏BepInEx会自动完成初始化生成BepInEx文件夹及其子目录。安装AutoTranslator从AutoTranslator的GitHub发布页下载对应BepInEx版本的插件包如XUnity.AutoTranslator-BepInEx-5.4.xx.zip。将其解压把里面的plugins文件夹整个复制到游戏根目录的BepInEx文件夹下。如果提示合并选择“是”。验证安装启动游戏。如果安装成功你通常会在游戏窗口的左上角看到一行小字例如“XUnity Auto Translator Initialized”或者按Alt0能调出翻译配置窗口。注意有些游戏可能使用了特殊的IL2CPP后端编译对Hook的支持不完善。如果遇到翻译不生效或游戏崩溃可能需要额外安装AutoTranslator.IL2CPP.BruteForceFix等辅助插件或者检查游戏社区是否有特定的安装指南。3.2 核心配置文件详解安装完成后在BepInEx\plugins\XUnity.AutoTranslator目录下你会找到核心配置文件Config.ini。这个文件控制着插件的所有行为。我们挑几个最关键的部分进行配置[General] ; 翻译服务端点例如GoogleTranslate, GoogleTranslateLegitimate, BingTranslate, BaiduTranslate, DeepL等 EndpointGoogleTranslate ; 源语言游戏文本的语言 Languageja ; 目标语言你想翻译成的语言 DestinationLanguagezh-CN ; 输出翻译文件的目录{GameExeName}和{Lang}是占位符 OutputPathTranslation\{GameExeName}\{Lang}\Text\_AutoGeneratedTranslations.txt这是最基础的配置告诉插件使用谷歌翻译免费公开接口从日文翻译到简体中文并将生成的翻译对保存到指定目录。[Behaviour] ; 是否启用UI自动重排。翻译后文本可能变长启用此项会尝试调整文本框大小以适应内容。 EnableUIResizingTrue ; 最大翻译字符数超过此长度的文本将被忽略。防止翻译过长的代码或错误信息。 MaxCharactersPerTranslation400 ; 是否启用文本路径日志。调试时非常有用可以输出每个文本组件在游戏对象树中的完整路径。 EnableTextPathLoggingFalseEnableUIResizing对于视觉小说这类UI布局固定的游戏至关重要。如果关闭长文本可能会被截断显示不全。3.3 配置在线翻译服务免费公开的谷歌翻译接口EndpointGoogleTranslate通常可以直接使用但可能不稳定或有速率限制。如果你有相应API的密钥建议使用认证接口以获得更好服务。以DeepL为例前往DeepL官网注册并获取API密钥。在Config.ini中找到[DeepLLegitimate]部分。修改配置[General] EndpointDeepLLegitimate ... [DeepLLegitimate] ; 填入你的DeepL API密钥 ApiKeyyour-deepl-api-key-here ; 如果你使用的是免费版API设置为True FreeFalse将[General]部分的Endpoint改为DeepLLegitimate。以百度翻译为例前往百度翻译开放平台注册创建应用获取App ID和密钥。修改配置[General] EndpointBaiduTranslate ... [Baidu] BaiduAppIdyour_app_id BaiduAppSecretyour_app_secret配置完成后启动游戏尝试触发一些游戏内文本如打开菜单、进行对话。按Alt0打开翻译器窗口你应该能看到翻译请求的状态。同时在BepInEx\plugins\XUnity.AutoTranslator\Translation\MyFantasyGame\zh-CN\Text\目录下会逐渐生成一个_AutoGeneratedTranslations.txt文件里面保存了所有已翻译的文本对。4. 高级技巧与深度定制超越基础翻译当基础翻译工作流跑通后你会发现很多细节问题。比如翻译质量不佳、UI错位、特殊格式文本处理等。这时就需要用到AutoTranslator提供的高级功能。4.1 手动翻译与词条管理完全依赖机器翻译质量难以保证。AutoTranslator允许你进行精细化的手动修正。直接编辑缓存文件打开_AutoGeneratedTranslations.txt你会看到类似这样的行Item acquired!获得物品 Press [Button] to interact.按[按钮]互动。你可以直接修改等号右侧的译文。保存文件后在游戏中按AltR即可重载翻译立即看到修改效果。这是最直接的优化翻译质量的方式。创建独立翻译文件不建议直接大量修改自动生成的文件因为游戏更新或重新生成时可能会被覆盖。更好的做法是新建一个.txt文件例如MyManualTranslations.txt放在同一个Text目录下。将你需要修正的词条复制进去并修改。插件会读取该目录下所有.txt文件且手动文件的优先级高于自动生成的文件。使用正则表达式Regex处理复杂文本游戏文本常常带有变量或格式。例如伤害提示可能是“You dealt 150 damage!”。直接翻译“You dealt”和“damage!”会导致数字部分也被翻译或丢失。这时可以使用正则表达式r:^You dealt ([0-9]) damage!$你造成了$1点伤害以r:开头的行表示一个正则表达式翻译规则。([0-9])捕获了伤害数字并在译文中用$1引用。更强大的拆分器正则表达式Splitter Regex对于组合文本如“01 Healing Potion”、“02 Mana Potion”如果物品名“Healing Potion”和“Mana Potion”已有翻译可以使用拆分器sr:^([0-9]{2}) ([\S\s])$$1 $2以sr:开头。这个规则会将“01 Healing Potion”拆分成“01”和“Healing Potion”两部分分别进行翻译查找数字部分通常不会被翻译然后再组合成“01 治疗药水”。4.2 解决UI显示问题字体与重排翻译为中文等非拉丁语系语言后最大的挑战是字体和布局。字体替换许多游戏的默认字体不包含中文字符集会导致中文显示为方框□□□。AutoTranslator支持字体覆盖。获取字体文件你需要一个包含目标语言字符的.ttf或.otf字体文件。创建字体AssetBundle针对UGUI这需要用到Unity Editor。创建一个新项目版本尽量与目标游戏一致。将字体文件导入并为它创建一个材质Material。然后通过Unity的AssetBundle构建系统将字体和材质打包成一个.assets文件。这是一个相对专业的步骤社区常有分享现成的中文字体AssetBundle。配置将生成的.assets文件放入游戏根目录。在Config.ini中设置[Font] ; 填写你的字体AssetBundle文件名不含路径 OverrideFontMyChineseFont.assets对于使用TextMeshProTMP的游戏过程更简单一些可以直接指定系统字体或TMP自带的字体资源名[Font] ; 使用TMP自带的Arial SDF字体需游戏包含此资源 OverrideFontTextMeshProFonts Materials/ARIAL SDF ; 或者添加一个后备字体 FallbackFontTextMeshProFonts Materials/LiberationSans SDF FallbackUI组件重排即使有了正确字体文本长度变化也可能导致布局混乱。除了启用EnableUIResizing你还可以创建resizer.txt文件进行像素级控制。在Text目录下创建resizer.txt。使用EnableTextPathLoggingTrue运行游戏触发需要调整的文本在游戏日志或输出框中找到该文本组件的完整路径。在resizer.txt中添加规则。例如路径为Canvas/Panel/DescriptionText的组件字体太大你可以将其缩小到80%Canvas/Panel/DescriptionTextChangeFontSizeByPercentage(0.8)你也可以同时应用多个命令用分号隔开Canvas/Panel/ButtonLabelChangeFontSize(24);UGUI_HorizontalOverflow(overflow)4.3 资源重定向翻译图片与替换游戏文件AutoTranslator不仅能翻译文本还能替换游戏内的图片资源如带有文字的UI图标、标题图。启用纹理翻译在Config.ini中设置[Texture] EnableTextureTranslationTrue TextureDirectoryTranslation\Texture EnableTextureDumpingTrue ; 首次使用时开启用于导出游戏内图片导出图片启动游戏遍历各个界面。插件会将游戏用到的纹理图片导出到TextureDirectory指定的目录下文件名会包含一个哈希值用于标识如title_logo [ABCD1234-EF567890].png。编辑图片用图像处理软件如Photoshop, GIMP打开导出的图片将其中的外文文字修改为中文务必保持图片尺寸和文件名包括哈希值完全不变。关闭导出启用替换编辑完成后将EnableTextureDumping设为False再次启动游戏。插件就会加载你修改后的图片替换游戏中原有的图片。重要警告EnableTextureDumping、EnableTextureToggling、LoadUnmodifiedTextures等选项会显著影响性能且导出的图片可能包含游戏版权内容。绝对不要在公开发布的翻译补丁中开启这些选项仅用于本地调试和制作。5. 疑难杂症与性能优化在实际使用中你肯定会遇到各种奇怪的问题。这里总结一些常见坑点和解决方案。5.1 常见问题排查表问题现象可能原因解决方案游戏启动崩溃或报错1. BepInEx/AutoTranslator版本与游戏不兼容。2. 游戏为IL2CPP编译且未使用BruteForceFix。3. 与其他Mod冲突。1. 尝试更换BepInEx或AutoTranslator的版本如稳定版vs测试版。2. 寻找并安装针对IL2CPP的辅助插件。3. 暂时移除其他Mod逐一排查。翻译完全不生效1. 插件未正确加载。2. 源语言/目标语言设置错误。3. 游戏使用非常规的文本渲染方式。1. 检查游戏根目录下BepInEx\plugins\XUnity.AutoTranslator是否存在按Alt0看能否调出窗口。2. 确认Language和DestinationLanguage设置正确如日语是ja简体中文是zh-CN。3. 尝试开启EnableIMGUITrue如果游戏用旧版IMGUI或检查游戏是否使用自定义文本组件。部分文本未被翻译1. 文本长度超过MaxCharactersPerTranslation限制。2. 文本被游戏逻辑动态拼接。3. 该文本组件被插件忽略如名称含XUAIGNORE。1. 适当调大MaxCharactersPerTranslation但不要超过1000。2. 使用拆分器正则表达式sr:处理。3. 检查游戏日志看该文本是否被标记为“不可翻译”。翻译后游戏逻辑出错游戏通过检查显示的文本来决定后续行为常见于一些老旧或特殊引擎的游戏。在[Behaviour]部分设置TextGetterCompatibilityModeTrue。这个模式会“欺骗”游戏让它认为显示的仍是原文。在线翻译失败1. 网络问题。2. 翻译API密钥无效或配额用尽。3. 公开API接口被屏蔽或限制。1. 检查网络连接。2. 核对API配置尝试在浏览器中直接调用API验证。3. 更换其他翻译端点如从GoogleTranslate换为BaiduTranslate或使用离线词典模式。内存占用过高或游戏变卡1. 开启了纹理导出(EnableTextureDumping)。2. 缓存了过多纹理(CacheTexturesInMemoryTrue)。3. 正则表达式过于复杂或范围太广。1.务必在导出所需图片后关闭EnableTextureDumping。2. 如果不需要纹理翻译关闭EnableTextureTranslation如果内存紧张可设CacheTexturesInMemoryFalse。3. 优化正则表达式避免使用.*这种贪婪匹配尽量精确限定范围。5.2 性能优化与最佳实践善用缓存减少在线请求首次游玩时让插件生成完整的_AutoGeneratedTranslations.txt。之后你可以将此文件分享给其他玩家他们放入对应目录后游戏内绝大部分文本都直接从本地缓存读取无需联网速度极快且稳定。这是制作发布翻译补丁的标准做法。翻译范围限定使用翻译作用域Scoping来提升性能。在翻译文件中使用#set level 2或#set exe GameA等指令可以让特定翻译只在对应的游戏场景或可执行文件下生效避免不必要的字典查找。关闭调试选项在正常使用非调试时确保[Debug]部分的EnableLog和EnableConsole为False[Behaviour]下的EnableTextPathLogging也为False。这些日志输出会影响性能。批处理翻译请求确保[Behaviour]下的EnableBatchingTrue默认。这允许插件将多个短文本合并为一个请求发送给翻译API减少网络开销和API调用次数。谨慎使用正则和纹理复杂的正则表达式全局匹配和全场景纹理扫描EnableTextureScanOnSceneLoad是性能杀手。只在必要时使用并尽量优化其模式。6. 从玩家到贡献者参与社区与制作补丁当你熟练使用AutoTranslator后你可能不再满足于个人使用而是想为自己热爱的游戏制作一个完整的翻译补丁分享给社区。制作可发布的翻译补丁清理缓存文件使用OutputUntranslatableTextFalse运行游戏确保_AutoGeneratedTranslations.txt中没有混杂不可翻译的垃圾文本如代码、变量名。仔细校对和润色其中的机器翻译。整理资源将你修改好的翻译文件.txt、可能用到的字体文件.assets或.ttf和替换的图片.png等整理好。提供配置文件可选但推荐你可以提供一个预配置好的Config.ini将Endpoint设为空Endpoint这样补丁默认使用离线缓存文件避免用户需要配置API。同时关闭所有调试和导出选项。编写说明文档创建一个README.txt说明补丁适用的游戏版本、安装方法通常是解压到游戏根目录、已知问题等。测试在一个纯净的游戏环境中测试你的补丁确保安装后能立即生效没有崩溃或严重bug。参与开源与进阶开发 AutoTranslator本身是开源项目。如果你懂C#编程你可以实现新的翻译端点参考项目中的HttpEndpoint基类为新的翻译服务如腾讯云翻译、阿里云翻译编写插件。开发资源重定向器针对特定游戏编写更精准的资源替换插件例如替换音频、模型等。贡献代码修复bug添加新功能优化性能。整个生态建立在社区共享的基础上。许多游戏的翻译补丁都可以在GitHub、Mod社区或专门的游戏论坛找到。在享受他人劳动成果的同时如果你有能力回馈社区将是推动这个生态持续发展的最好方式。