1. 项目概述当Unity游戏遇上语言壁垒如果你是一名Unity游戏玩家尤其是喜欢探索那些来自海外独立开发者或特定文化圈作品的玩家大概率遇到过这样的困境游戏界面、对话、物品描述全是看不懂的外文。对于开发者而言想要将一款游戏推向全球市场本地化Localization又是一项耗时耗力、成本高昂的系统工程。传统的本地化需要修改游戏源代码、处理资源文件、协调翻译团队流程复杂且难以维护。有没有一种方法能让我们像给浏览器装翻译插件一样为已编译的Unity游戏实时注入翻译甚至允许社区玩家自行制作和分享翻译补丁呢XUnity.AutoTranslator以下简称XUAT正是为解决这一痛点而生的终极工具。它不是一个简单的文本替换器而是一个运行在游戏进程内的、高度可配置的翻译框架。其核心原理是通过“注入”Hooking技术拦截游戏运行时对文本和资源的调用在内存中将源语言内容替换为目标语言内容从而实现“无侵入式”的实时翻译。这意味着你不需要反编译游戏、不需要修改原始游戏文件只需要将XUAT作为插件安装到游戏目录配置好翻译引擎如谷歌翻译、百度翻译等或加载已有的翻译文件就能立刻在游戏中看到母语内容。从玩家角度看它是打破语言障碍的神器从Mod作者和社区汉化组角度看它提供了一个稳定、强大且可扩展的本地化框架极大地降低了制作和维护翻译补丁的门槛。项目在GitHub上由bbepis维护历经多年迭代功能已从最初的文本翻译扩展到纹理替换、资源重定向、正则表达式处理、字体覆盖等深度定制领域堪称Unity游戏本地化领域的“瑞士军刀”。2. 核心架构与工作原理解析要理解XUAT的强大之处必须深入其架构。它并非单一模块而是一个以“XUnity.AutoTranslator.Plugin.Core”为核心协同“XUnity.ResourceRedirector”等支持库工作的生态系统。2.1 核心翻译流程从拦截到呈现XUAT的翻译行为可以概括为一个高效的“侦听-查询-替换”流水线。第一步文本钩取Hooking游戏中的所有文本最终都需要通过Unity引擎的UI组件如UnityEngine.UI.Text、TextMeshPro来显示。XUAT在游戏启动时会利用Harmony或备选的MonoMod这类函数钩取库将这些UI组件中设置文本的方法例如Text.set_text进行拦截。当游戏代码调用这些方法试图显示“こんにちは”时调用会被XUAT截获。第二步文本查询与匹配截获原始文本后XUAT不会立即发送给在线翻译API。它首先会查询一个本地的翻译缓存字典。这个字典的数据来自两个地方自动生成的翻译文件(_AutoGeneratedTranslations.txt)当插件遇到新文本且在线翻译成功时会将“原文译文”对记录在此文件中。手动创建的翻译文件用户或汉化组可以创建任何.txt文件放置于Translation/{Lang}/Text/目录下格式同样是“原文译文”。这些文件的优先级高于自动生成的文件。插件会进行智能匹配不仅匹配完全相同的字符串还会处理首尾空格、内部换行符等差异。例如游戏可能在对话历史和实际对话中使用同一句文本但后者多了一个换行符。XUAT的匹配逻辑能识别这种“兼容”情况确保只需一份翻译即可覆盖多种表现形式。第三步翻译获取如果在本地缓存中未找到匹配项XUAT会根据配置将文本发送给指定的翻译终端Endpoint。它内置支持了众多翻译服务如Google Translate、Baidu Translate、DeepL等。你可以通过简单的配置切换服务商。翻译成功后结果会被存入本地缓存并显示在游戏中同时追加到自动生成文件中实现“边玩边学”下次遇到相同文本就无需联网。第四步渲染与适配获取到翻译文本后XUAT将其设置回UI组件。但翻译常导致文本长度变化如英文译成中文通常变短日文译成英文通常变长。为此XUAT提供了强大的UI自适应功能自动重设大小通过EnableUIResizing选项插件会自动调整文本框的HorizontalOverflow和VerticalOverflow属性允许文本换行或溢出避免显示不全。字体回退与替换游戏原字体可能不包含目标语言的字符如中文。XUAT允许你指定一个备用字体FallbackFontTextMeshPro或直接覆盖所有字体OverrideFontTextMeshPro确保特殊字符正确显示。手动UI调整对于复杂UI你可以编写resizer.txt规则文件精确控制特定路径下UI元素的字体大小、行间距等属性。2.2 资源重定向器超越文本的本地化文本翻译只是本地化的一部分。游戏中的图片、图标可能也包含文字。XUAT通过其兄弟库“Resource Redirector”实现了资源级别的重定向。原理Resource Redirector 钩住了Unity的Resources.Load和AssetBundle.LoadAsset等核心资源加载API。当游戏尝试加载一个纹理Texture或文本资源TextAsset时重定向器会先检查配置的路径如Translation/Texture/下是否存在同名或同哈希值的已修改资源。如果存在则加载修改后的版本如果不存在则按游戏原路径加载。应用场景纹理替换将游戏内的日文按钮图标替换为中文版本。你只需要将翻译好的图片按照特定命名规则包含资源哈希值放入TextureDirectory启用EnableTextureTranslation即可。直接修改游戏资源通过启用EnableTextAssetRedirector游戏加载的所有文本资源如配置表、剧情脚本都会被导出到本地文件。你可以直接编辑这些文件修改后再放回原目录游戏就会加载你修改后的版本。这比直接拆包修改AssetBundle要安全且易于维护。2.3 插件化与扩展性XUAT的设计极具开放性。它不仅仅是一个封闭的工具更是一个平台。自定义翻译终端如果你有自己的翻译API或想集成小众翻译服务可以参照ITranslateEndpoint接口实现自己的翻译器DLL放入Translators文件夹即可被识别和使用。与其他Mod交互XUAT提供了API供其他Mod调用以查询翻译或告知XUAT不要翻译特定Mod的UI通过在GameObject名称中包含XUAIGNORE。资源重定向API对于高级开发者Resource Redirector提供了完整的API允许你编写Mod来动态修改游戏加载的任何资源模型、音频、动画等远超本地化的范畴可用于制作各种游戏内容修改Mod。3. 实战部署从零开始配置你的游戏翻译理论说得再多不如动手实践。下面我将以一款典型的Unity游戏为例演示如何部署和配置XUAT。3.1 环境准备与插件安装首先你需要确定游戏使用的Mod加载器。XUAT支持主流的三种BepInEx目前最流行的Unity游戏Mod框架通用性最强。推荐使用BepInEx 5.x或6.x版本。IPA主要用于Illusion社的游戏。ReiPatcher较老的注入工具。安装步骤以BepInEx为例从GitHub的Releases页面下载对应你游戏架构通常是x86的XUnity.AutoTranslator-BepInEx-{VERSION}.zip。将压缩包内的所有文件解压到游戏的根目录即包含Game.exe和BepInEx文件夹的目录。通常结构会是你的游戏/ ├── Game.exe ├── BepInEx/ │ ├── core/ │ ├── plugins/ │ │ └── XUnity.AutoTranslator/ -- 插件核心文件在这里 │ └── ... (其他BepInEx文件) └── ... (其他游戏文件)启动游戏。如果安装成功游戏启动时在日志中会看到XUAT的初始化信息。首次运行后会在BepInEx/plugins/XUnity.AutoTranslator目录下生成配置文件Config.ini和翻译目录Translation。3.2 核心配置详解让翻译引擎跑起来配置文件Config.ini是XUAT的大脑。用文本编辑器打开它我们重点关注[General]和[Service]段。[General] ; 游戏内显示的语言 Languagezh-CN ; 翻译服务终端例如GoogleTranslate, BaiduTranslate, DeepLTranslate留空则禁用自动翻译 EndpointGoogleTranslate ; 是否启用IMGUI翻译常用于翻译其他Mod的界面 EnableIMGUIFalse [Service] ; 在线翻译的延迟设置防止请求过快被屏蔽 MinDelay0 MaxDelay1关键配置解析Language: 设置目标语言代码如zh-CN简体中文、en英文、ja日文。这决定了在线翻译的目标语言和本地翻译文件的查找路径Translation/zh-CN/。Endpoint: 这是最重要的设置之一。它决定了使用哪个在线翻译服务。内置选项包括GoogleTranslate: 谷歌翻译免费但可能需要网络环境。BaiduTranslate: 百度翻译需要配置AppID和密钥国内访问稳定。DeepLTranslate: DeepL翻译质量高但免费版有限额。None或留空完全禁用在线翻译仅使用本地翻译文件。EnableIMGUI: 许多游戏Mod使用旧的IMGUI系统制作界面。开启此项可以尝试翻译这些Mod的UI但可能造成冲突或不稳定建议按需开启。配置在线翻译API以百度翻译为例如果你选择BaiduTranslate需要在Config.ini中找到[Baidu]段并填入你在百度翻译开放平台申请的AppId和AppSecret。[Baidu] BaiduAppId你的AppId BaiduAppSecret你的AppSecret注意严禁在公开分享的翻译补丁包中附带任何他人的或未授权的API密钥。分发时应将Endpoint设为空并依赖完整的本地翻译文件。3.3 翻译文件管理与高级技巧安装并配置好基础翻译服务后游戏中的新文本会被自动翻译并保存到Translation/{Lang}/Text/_AutoGeneratedTranslations.txt。但这个文件是自动管理的不建议直接编辑。正确的做法是1. 创建手动翻译文件在Translation/zh-CN/Text/目录下新建一个.txt文件例如MainStory.txt。格式非常简单原文句子1翻译后的句子1 原文句子2翻译后的句子2保存后重启游戏或按AltR热键重载翻译新翻译就会立即生效。手动文件的优先级高于自动生成文件。2. 使用正则表达式处理动态文本游戏中的文本常常包含变量例如“你获得了 {itemName} x{count}”。直接翻译“你获得了 生命药水 x5”是无效的因为下次可能是“你获得了 魔力药水 x3”。 XUAT支持正则表达式翻译r:^你获得了 (.) x(\d)$You got $1 x$2以r:开头的行会被识别为正则表达式。$1,$2对应正则中捕获的组。更强大的是“分割器正则”sr:它可以将一个复合字符串拆分成多个部分分别翻译后再组合非常适合处理带前缀编号或格式固定的文本。3. 翻译作用域控制你可以通过指令将翻译限定在特定场景或游戏可执行文件避免翻译冲突。#set level 5 BOSS战提示小心他的冲锋 #unset level 5这行翻译只会在场景ID为5时生效。你可以按CtrlAltNumPad7查看当前场景ID。4. 字体配置如果翻译后文字显示为方块说明游戏字体缺失字形。你需要准备一个包含目标语言字符的字体文件通常是.ttf或.otf并使用Unity编辑器将其制作成TextMeshPro可用的字体AssetSDF Font Asset。将生成的Asset文件或包含它的AssetBundle放入游戏目录然后在配置中指定[Behaviour] OverrideFontTextMeshProFonts/MyChineseFont SDF或者使用更安全的回退字体方案FallbackFontTextMeshProFonts/MyChineseFont SDF4. 疑难杂症排查与性能调优即使配置正确在实际使用中也可能遇到各种问题。以下是一些常见故障及其解决方法。4.1 翻译不生效或游戏崩溃问题现象游戏启动正常但文字毫无变化或者启动即闪退/卡死。排查步骤检查日志确保BepInEx的日志输出是开启的通常会在游戏根目录生成LogOutput.log或控制台窗口有输出。查看其中是否有XUAT相关的错误信息如“Failed to hook...”或“Initialization failed...”。确认Mod加载器兼容性确保你下载的XUAT版本与游戏的Mod加载器BepInEx 4.x vs 5.x/6.x匹配。BepInEx 5.x的插件通常不向下兼容。检查游戏架构确认下载的XUAT插件版本x86/x64与游戏可执行文件Game.exe的架构一致。可通过工具如Dependencies查看Game.exe是32位还是64位。禁用其他Mod与其他Mod冲突是常见原因。尝试移出其他所有Mod只保留XUAT看问题是否解决。如果解决再逐一放回以定位冲突Mod。尝试兼容模式在Config.ini中设置TextGetterCompatibilityModeTrue。有些游戏会检查显示的文本内容来决定后续逻辑比如根据关键词跳转剧情直接替换文本会导致游戏逻辑错误。此模式会“欺骗”游戏让它认为显示的仍是原文。IL2CPP特殊处理对于使用IL2CPP后端编译的游戏多见于手游移植或较新Unity版本XUAT的文本钩取能力有限。你可能需要额外安装AutoTranslator.IL2CPP.BruteForceFix这个辅助插件来强制刷新文本。4.2 翻译质量差或格式错乱问题现象翻译结果生硬、错误或者换行、空格处理不当导致UI布局混乱。优化策略调整空格处理对于视觉小说VN或带有大量对话的游戏不当的换行符会导致在线翻译API将一段话拆成多句独立翻译破坏连贯性。在Config.ini中调整[Behaviour] IgnoreWhitespaceInDialogueTrue MinDialogueChars20这会让插件在翻译长对话时先移除内部的空白字符如换行将整段文本作为一个整体发送给翻译API质量更高。使用预处理与后处理你可以创建Preprocessors.txt和Postprocessors.txt文件。前者在翻译前修改原文如替换游戏内特定的错误音译名后者在翻译后修改译文如统一角色称呼、调整语气词。善用本地词典将频繁出现、翻译API总是翻错的专有名词角色名、技能名、物品名直接写入手动翻译文件。XUAT会优先使用本地精确匹配避免每次联网都产生错误翻译。UI重设与字体如果翻译后文字显示不全务必开启EnableUIResizingTrue。对于复杂UI可能需要手动编写resizer.txt规则。字体问题必须通过配置回退或覆盖字体解决。4.3 性能问题与网络请求优化问题现象游戏卡顿、翻译延迟高或者在线翻译服务频繁报错、触发限流。调优方案启用请求批处理在Config.ini中设置EnableBatchingTrue。这会将短时间内出现的多个短文本合并成一个请求发送大幅减少API调用次数尤其适合翻译密集的对话场景。限制翻译长度设置MaxCharactersPerTranslation400。避免将过长的文本如整本书发送给API这既容易超时也可能违反服务条款。增加请求延迟调整[Service]下的MinDelay和MaxDelay。例如设置为MinDelay1和MaxDelay3让插件在每次翻译请求间随机等待1-3秒减轻服务器压力避免IP被屏蔽。构建完整的本地缓存在游玩过程中XUAT生成的_AutoGeneratedTranslations.txt会越来越丰富。在准备分享给他人或自己重装游戏时将这个文件作为翻译补丁的核心分发。接收者只需将此文件放入对应目录并将Endpoint设为空即可获得完整的离线翻译体验零延迟、零网络请求。谨慎使用纹理翻译纹理替换EnableTextureTranslation和纹理扫描EnableTextureScanOnSceneLoad是非常消耗内存和加载时间的操作。除非必要不要开启。如果开启务必设置CacheTexturesInMemoryTrue以避免重复加载并确保TextureHashGenerationStrategyFromImageName以获取最佳性能。4.4 制作与分发翻译补丁的注意事项当你完成了一个游戏的翻译想要打包分享给社区时请遵循以下准则这对维护者声誉和项目健康至关重要清理自动生成文件在打包前请仔细检查_AutoGeneratedTranslations.txt移除其中的无意义翻译如单个字符、乱码、UI技术字符串。一个干净、精准的翻译文件是高质量补丁的标志。禁用在线翻译端点在分发的Config.ini中必须将Endpoint设置为空或None。绝对不要包含任何第三方翻译服务的API密钥或配置。你的补丁应提供完整的本地化体验而不是引导用户去配置可能失效或非法的在线服务。包含字体资产如果使用了自定义字体请确保字体文件或AssetBundle一并打包并提供清晰的安装说明。注意字体版权使用开源字体或已获授权的字体。注明XUAT版本与游戏版本在README中明确说明该翻译补丁基于哪个版本的XUnity.AutoTranslator制作以及适用的游戏版本例如v1.2.3。不同版本的XUAT在配置和功能上可能有差异。测试与反馈在多个游戏场景中进行测试确保翻译覆盖全面且无崩溃。提供一个渠道如GitHub Issues让用户报告未翻译的文本或错误。5. 开发者视角扩展XUAT的无限可能对于有一定C#编程基础的Mod开发者或汉化组技术成员XUAT开放的API提供了广阔的定制空间。5.1 实现一个自定义翻译终端假设你所在社区搭建了一个内部使用的术语库API希望XUAT优先使用它进行翻译。你可以创建一个独立的类库项目。创建项目在Visual Studio中新建一个.NET Framework 3.5类库项目与Unity游戏运行时兼容。引用核心库添加对XUnity.AutoTranslator.Plugin.Core.dll从开发者包中获取的引用。实现接口创建一个类实现ITranslateEndpoint接口或继承HttpEndpoint基类。using XUnity.AutoTranslator.Plugin.Core; using XUnity.AutoTranslator.Plugin.Core.Endpoints; using XUnity.AutoTranslator.Plugin.Core.Endpoints.Http; using System; using System.Collections; public class MyCommunityTranslatorEndpoint : HttpEndpoint { public override string Id MyCommunityTranslator; public override string FriendlyName My Community Glossary; private string _apiBaseUrl; public override void Initialize(IInitializationContext context) { // 从配置文件读取API地址 _apiBaseUrl context.GetOrCreateSetting(MyCommunity, ApiBaseUrl, https://api.mycommunity.com/translate); // 如果你的API是自签证书可能需要禁用证书检查谨慎使用 // context.DisableCertificateChecksFor(api.mycommunity.com); // 验证语言支持等 if (context.DestinationLanguage ! zh-CN) { throw new Exception(本术语库目前仅支持翻译为简体中文。); } } public override void OnCreateRequest(IHttpRequestCreationContext context) { // 构建HTTP请求 var url ${_apiBaseUrl}?text{Uri.EscapeDataString(context.UntranslatedText)}to{context.DestinationLanguage}; var request new XUnityWebRequest(url); request.Headers[System.Net.HttpRequestHeader.Accept] application/json; context.Complete(request); } public override void OnExtractTranslation(IHttpTranslationExtractionContext context) { // 解析API返回的JSON var json context.Response.Data; // 这里简化处理实际应使用JSON解析库如SimpleJSON // 假设返回格式{translatedText: 你好世界} if (json.Contains(\translatedText\:\)) { var start json.IndexOf(\translatedText\:\) 18; var end json.IndexOf(\, start); var translatedText json.Substring(start, end - start); context.Complete(translatedText); } else { context.Fail(无法从响应中解析出翻译文本。); } } }编译与部署将编译好的DLL文件放入游戏的BepInEx/plugins/XUnity.AutoTranslator/Translators/目录。在Config.ini中设置EndpointMyCommunityTranslator并配置对应的[MyCommunity]段参数即可使用。5.2 利用资源重定向进行深度修改Resource Redirector的API允许你进行更底层的游戏修改。例如你想修改某个特定NPC的模型。using XUnity.ResourceRedirector; using UnityEngine; public class MyModelReplacerPlugin { public void Awake() { // 在资源加载后钩子中替换模型 ResourceRedirection.RegisterAssetLoadedHook( HookBehaviour.OneCallbackPerResourceLoaded, 100, // 优先级 OnAssetLoaded); } private void OnAssetLoaded(AssetLoadedContext context) { // 检查加载的资源是否是我们要替换的NPC预制体 if (context.Parameters.Name ! Prefabs/NPCs/OldVillager) return; if (!(context.Asset is GameObject originalPrefab)) return; // 防止递归调用 context.DisableRecursion(); // 从我们自己的AssetBundle中加载新的模型预制体 var myBundle AssetBundle.LoadFromFile(MyMods/NewVillager.bundle); var newVillagerPrefab myBundle.LoadAssetGameObject(NewVillager); if (newVillagerPrefab ! null) { // 替换资源 context.Asset newVillagerPrefab; Debug.Log(成功替换老村民模型); } myBundle.Unload(false); context.Complete(true); // 跳过后续的钩子 } }这段代码演示了如何监听资源加载事件并在加载特定NPC预制体时动态替换为来自外部AssetBundle的新模型。这为游戏Mod开发打开了无限可能从简单的贴图替换到复杂的游戏机制修改都能实现。XUnity.AutoTranslator的成功在于它精准地抓住了Unity游戏本地化过程中的核心痛点——无需源码、实时生效、社区驱动、高度可扩展。它从一个翻译插件成长为一个功能强大的游戏修改中间件。无论是普通玩家寻求即时的语言解决方案还是汉化组构建系统化的翻译工程亦或是Mod开发者探索游戏内容替换的边界XUAT都提供了一个坚实、可靠且充满可能性的平台。它的存在极大地降低了跨语言游戏体验和内容创作的门槛让更多优秀的作品得以被全世界玩家所理解和喜爱。在使用的过程中尊重原作者的劳动遵守翻译服务的条款积极回馈社区这套工具的价值才能被长久地发挥和延续下去。
)
