1. 项目概述一个为Unity游戏而生的“翻译官”如果你是一名热爱日系或独立游戏的玩家或者是一名游戏汉化组的成员那么你一定对“游戏内文本翻译”这个需求不陌生。面对那些没有官方中文、文本又深嵌在游戏资源里的作品传统的汉化方式往往意味着繁琐的资源解包、文本提取、翻译、再打包整个过程不仅技术门槛高而且一旦游戏更新汉化补丁就可能失效让人头疼不已。XUnity.AutoTranslator后文简称XUA的出现正是为了解决这个痛点。它不是一个简单的文本替换工具而是一个运行在游戏进程内的、高度智能的翻译插件。其核心思路是“运行时拦截与替换”在游戏运行时动态拦截Unity引擎渲染到屏幕上的每一段文本将其发送到配置好的翻译服务如谷歌翻译、百度翻译等进行实时翻译再将翻译结果无缝替换回游戏界面。这意味着你无需修改游戏的任何原始文件就能实现“即开即用”的游戏内翻译。对于玩家而言它降低了体验外语游戏的门槛对于汉化者而言它提供了一套可编程、可扩展的现代化汉化框架。这个开源项目在GitHub上由bbepis维护其亮点远不止“自动翻译”四个字。它集成了资源重定向、字体替换、UI自适应、正则表达式处理、插件化翻译端点等高级功能形成了一个功能强大且生态开放的解决方案。接下来我将从一个资深插件使用者和开发者的角度为你深度解析XUA那些令人印象深刻的亮点与核心机制。2. 核心架构与设计哲学不仅仅是“翻译”2.1 运行时Hook与无侵入式修改XUA的基石是其强大的运行时Hook能力。它主要依赖于两个底层库Harmony或可选的MonoMod来实现对Unity引擎内部方法的拦截。当游戏调用诸如TextMeshPro.text或UnityEngine.UI.Text.text的setter属性时XUA的代码会抢先一步执行。其工作流程可以简化为检测插件检测到游戏试图设置一段文本到UI组件上。拦截Hook方法捕获这段原始文本例如日文“こんにちは”。查询首先在本地翻译缓存文件如_AutoGeneratedTranslations.txt中查找是否有现成的翻译。翻译若缓存未命中则根据配置将文本发送至指定的在线翻译API如Google Translate。替换与渲染获取翻译结果如“你好”后将其设置回UI组件并触发必要的UI更新如字体重载、文本框大小调整。缓存将新的翻译对原始文本 - 翻译文本写入本地缓存文件供后续使用。这种设计的最大优势在于“无侵入性”。游戏本体文件保持原样所有翻译逻辑和缓存数据都存放在游戏目录下的独立文件夹如BepInEx/plugins/XUnity.AutoTranslator中。卸载插件只需删除该文件夹游戏即刻恢复原状。这完美解决了传统汉化补丁与游戏版本强绑定、易冲突的问题。2.2 模块化与生态扩展Resource Redirector的威力XUA不仅仅能处理动态文本其内置的**Resource Redirector资源重定向器**模块是一个更具革命性的设计。它是一个独立于自动翻译功能的通用库允许插件在游戏加载资源如AssetBundle、Resources文件夹中的资源的瞬间动态替换其内容。这意味着什么假设一个游戏的所有UI图片、字体文件都打包在AssetBundle里。传统汉化需要解包、修改图片、重新打包。而利用Resource Redirector你可以配置插件启用资源转储EnableTextureDumpingTrue。运行游戏插件会自动将游戏加载的所有纹理图片以带哈希值的文件名如button_icon [ABCD1234].png导出到指定目录。你用PS等工具修改这些图片例如将日文按钮图替换为中文。将修改后的图片放回原目录并启用纹理翻译EnableTextureTranslationTrue。再次运行游戏Resource Redirector会在游戏加载原始button_icon时拦截该请求并返回你修改后的中文图片文件。这个过程完全在内存中完成无需替换游戏原始资源包。这个模块的API甚至对其他插件开发者开放使得任何模组都可以利用它来安全地替换游戏内的音频、模型、文本资产等极大地扩展了Unity游戏Mod的可能性边界。2.3 配置驱动的灵活性XUA的另一个核心设计是高度的可配置性。几乎所有的行为都由一个Config.ini文件控制。从选择翻译引擎、设置并发请求数、配置缓存路径到精细控制空白符处理、UI重缩放策略、正则表达式规则都可以通过修改配置文件实现。这种设计将“使用”和“开发”清晰地分离开。普通用户只需在GUI按Alt0呼出中选择翻译语言和端点或简单修改几个配置项而高级用户和汉化组则可以通过编辑复杂的配置文件实现近乎定制化的翻译行为例如为特定场景Level Scope或特定可执行文件Exe Scope应用不同的翻译规则或者使用正则表达式精准处理游戏内复杂的字符串拼接。3. 核心功能亮点深度剖析3.1 智能文本处理与缓存机制XUA的文本处理逻辑非常细腻考虑到了游戏开发中各种复杂的文本呈现情况。空白符与换行符的智能处理游戏文本中经常包含用于排版或对话控制的换行符\n、首尾空格等。直接将这些文本送去翻译可能会导致翻译API将换行前后的句子割裂处理产生糟糕的译文。XUA的IgnoreWhitespaceInDialogue和ForceSplitTextAfterCharacters等配置项就是为了在发送翻译前智能地清理和重组这些空白符确保送给翻译引擎的是语义连贯的整句翻译完成后再将必要的格式还原回去。四级文本查找策略为了提高缓存命中率和翻译准确性XUA对一个待翻译文本会进行四次递进式查找原始文本。去除首尾空白符的文本。去除内部非重复空白符如环绕换行符的空格的文本。同时进行2和3处理的文本。例如对于文本\n「今日はいい天気ですね。」\n插件会尝试查找「今日はいい天気ですね。」的翻译。只要缓存中存在这个核心句子的翻译无论其原始呈现时带有什么样的排版空白符都能被正确匹配并应用。这个设计极大地减少了重复翻译和缓存冗余。翻译作用域Scoping这是高级汉化的利器。通过#set level和#set exe等指令可以将特定的翻译条目限定在特定的游戏场景或特定的游戏启动程序下生效。这对于翻译那些在不同场景中重复使用但含义不同的文本比如通用菜单项和特定剧情文本或者为游戏的不同版本如Steam版和DMM版提供差异化翻译提供了完美的解决方案。3.2 强大的UI适配与字体管理自动翻译最大的视觉挑战之一是“文字溢出”。日文、中文等语言的字符宽度和排版习惯与英文不同直接替换后常导致文本超出文本框、显示不全或重叠。自动与手动UI重缩放XUA提供了双重解决方案。自动重缩放通过EnableUIResizing和ForceUIResizing插件可以尝试自动调整Text或TextMeshPro组件的HorizontalOverflow、VerticalOverflow、FontSize等属性让长文本能够换行或缩小显示。手动精准控制通过创建resizer.txt文件你可以为游戏中特定的UI组件路径指定精确的样式命令。例如TitleScreen/Canvas/Panel/DescriptionTextChangeFontSizeByPercentage(0.85);UGUI_HorizontalOverflow(wrap)这行配置会找到路径匹配TitleScreen/Canvas/Panel/DescriptionText的所有文本组件将其字体缩小至85%并将水平溢出模式改为自动换行。你可以使用开发者工具如Runtime Unity Editor或开启EnableTextPathLogging来获取游戏中每个文本组件的完整路径。字体替换与回退许多游戏的默认字体不包含中文等字符集导致翻译后显示为方框□□□。XUA的OverrideFontTextMeshPro和FallbackFontTextMeshPro配置项允许你指定一个包含目标语言字符集的字体文件如.ttf或.asset格式的TextMeshPro字体资源。插件会加载这个字体并替换或作为回退字体应用到所有文本组件上确保所有字符都能正确渲染。3.3 正则表达式与文本替换引擎对于结构化的游戏文本如物品名称属性[攻击力10] 钢铁长剑简单的字面翻译无法处理。XUA内置了完整的正则表达式支持分为两种模式标准正则翻译r:直接匹配并替换整个文本。适用于格式固定、需要整体处理的字符串。r:^獲得金 ([0-9]) G$获得金钱 $1 G拆分器正则sr:这是更强大的功能。它先将复合文本拆分成多个部分分别翻译再重新组合。这对于处理游戏动态拼接的文本尤其有效。sr:^([0-9]{2}) ([\S\s])$$1 $2假设游戏显示01 ポーション01 药水。上面的正则会将其拆分为01和ポーション。01作为数字不被翻译ポーション被单独查找翻译缓存假设缓存中有ポーション药水最后重组为01 药水。这避免了为01 ポーション、02 ポーション等每一个变体都单独创建翻译条目的麻烦。预处理与后处理Substitutions你还可以创建_Substitutions.txt文件在文本被送去翻译前进行简单的查找替换。例如将总是被误译的角色名「アリス」替换为一个占位符{{ALICE}}这样翻译引擎就不会去翻译这个名字翻译完成后再将{{ALICE}}替换回「爱丽丝」。这保证了专有名词翻译的一致性。3.4 插件化翻译端点与开发者生态XUA不仅是一个终端用户工具更是一个开发平台。它定义了ITranslateEndpoint接口允许开发者轻松集成任何翻译服务。实现自定义翻译器开发者只需创建一个继承自HttpEndpoint或直接实现ITranslateEndpoint的类完成Initialize初始化API密钥等、OnCreateRequest构建网络请求、OnExtractTranslation解析响应几个核心方法编译成DLL后放入Translators文件夹该翻译服务就会出现在插件的端点列表中。项目源码中已经提供了Google、Bing、DeepL、百度、Yandex等主流翻译的完整实现参考。这种设计意味着即使某个公共翻译API开始收费或改变接口社区也能快速响应开发出新的适配端点甚至集成本地运行的机器翻译模型如MarianMT实现完全离线的翻译体验。与其他Mod的互操作性XUA提供了API供其他Mod调用查询翻译AutoTranslator.Default.TranslateAsync。同时也提供了让其他Mod“屏蔽”自动翻译的机制在GameObject名称中包含XUAIGNORE避免了Mod界面被错误翻译的尴尬。对于IMGUI绘制的Mod界面则可以通过向XUA的GameObject发送DisableAutoTranslator/EnableAutoTranslator消息来临时关闭翻译确保自身UI的纯净。4. 高级配置与实战技巧4.1 性能调优与请求优化自动翻译插件在运行时进行网络请求和文本处理不当配置可能影响游戏流畅度。批量处理Batching务必开启EnableBatchingTrue。这会将短时间内产生的多个翻译请求合并为一个请求发送给翻译端点大幅减少网络连接数。对于按请求次数收费的API这也能节省成本。字符数限制MaxCharactersPerTranslation默认值为1000切勿随意调高。过长的文本如整本游戏说明书不仅翻译质量差还可能触发翻译API的请求限制或导致超时。对于超长文本应考虑通过资源重定向直接替换整个TextAsset。缓存策略翻译结果会优先从本地的_AutoGeneratedTranslations.txt读取。一个良好的实践是在游玩一段时间后将这个文件备份并手动校对、润色形成一个高质量的离线翻译库。下次游戏时将Endpoint设为空即可完全使用离线翻译实现零延迟、零网络依赖的完美体验。纹理翻译的权衡纹理替换功能强大但性能开销大。TextureHashGenerationStrategy首选FromImageName仅在哈希冲突导致图片错乱时才尝试FromImageData。CacheTexturesInMemoryTrue用内存换性能如果内存紧张可关闭。切记分发整合包时绝对不要开启EnableTextureDumping、LoadUnmodifiedTextures等调试选项。4.2 疑难杂症排查指南在实际使用中你可能会遇到各种问题以下是一些常见问题的排查思路问题翻译不生效或时有时无。检查按Alt0确认翻译端点已正确选择且在线。查看游戏目录下的LogOutput.logBepInEx日志或插件控制台是否有连接错误、认证失败API密钥错误或频率限制的报错。检查确认游戏文本组件类型是否被支持。XUA主要支持UGUI Text、TextMeshPro、部分NGUI和IMGUI。对于非常规或自定义组件可能需要开启EnableSpriteRendererHooking或TextGetterCompatibilityMode进行实验性尝试。检查文本是否被插件忽略查看配置中的IgnoreTextStartingWith或检查文本是否以不可见字符开头。问题翻译后游戏逻辑出错或崩溃。尝试启用TextGetterCompatibilityModeTrue。有些游戏会读取当前显示的文本来决定后续剧情分支或逻辑直接替换文本会导致游戏读取到翻译后的内容而逻辑错乱。此模式会“欺骗”游戏让它仍然读到原始文本。尝试对于IL2CPP编译的游戏翻译支持可能不完整。可以尝试使用项目提供的AutoTranslator.IL2CPP.BruteForceFix辅助插件。问题翻译后UI布局错乱文字重叠或显示不全。操作这是最常见的问题。首先尝试开启EnableUIResizingTrue。如果效果不佳则需要使用手动重缩放。操作开启EnableTextPathLoggingTrue在游戏中触发有问题的文本然后在日志中查找其完整路径。根据路径创建或修改resizer.txt文件为其指定合适的字体大小和溢出模式。操作如果翻译目标语言是非拉丁字符如中文务必配置FallbackFontTextMeshPro指向一个包含该语言字符集的字体文件。问题特定Mod的界面被错误翻译。解决找到该Mod生成的GameObject在其名称中加入XUAIGNORE忽略该物体或XUAIGNORETREE忽略该物体及其所有子物体。解决如果Mod使用IMGUI且你是该Mod的开发者可以在你的OnGUI方法中用GameObject.Find(___XUnityAutoTranslator)?.SendMessage(DisableAutoTranslator)和SendMessage(EnableAutoTranslator)包裹你的绘制代码。4.3 为特定游戏定制翻译包当你打算为一个游戏制作并分发一个高质量的翻译包时遵循以下流程可以事半功倍初始游玩与缓存生成正常安装插件并游玩游戏让插件自动生成_AutoGeneratedTranslations.txt。尽可能触发所有游戏文本。离线翻译与精校关闭在线翻译使用CAT计算机辅助翻译工具或文本编辑器对自动生成的翻译文件进行人工校对、润色和补全。这是一个耗时但提升体验最关键的一步。处理图片资源如果需要翻译图片UI开启EnableTextureDumping和EnableTextureScanOnSceneLoad遍历游戏所有场景导出所有纹理。用图像软件翻译后关闭转储选项开启EnableTextureTranslation。UI适配调整针对游戏中每个出现文字溢出或布局问题的UI使用EnableTextPathLogging找到路径并在resizer.txt中编写适配规则。这是一个细致活需要反复测试。整合与测试将校对后的文本文件、翻译好的图片、配置好的resizer.txt以及插件的核心DLL文件一起打包。确保配置文件中的调试选项如Dumping、Toggling已关闭MaxCharactersPerTranslation不超过400项目要求。分发说明在发布包中附带清晰的README说明安装方法、已知问题如某些场景翻译缺失、以及如何反馈错误。5. 开发者视角扩展与集成5.1 实现一个简单的自定义翻译端点让我们通过一个极简的示例看看如何为XUA添加一个将文本反转的“恶搞”翻译器。这有助于理解插件端点的工作流程。首先你需要创建一个新的.NET类库项目目标框架.NET 3.5或.NET Standard后者需修改csproj为net35以兼容旧版Unity。引用从XUA开发者包中获取的XUnity.AutoTranslator.Plugin.Core.dll。using XUnity.AutoTranslator.Plugin.Core; using XUnity.AutoTranslator.Plugin.Core.Endpoints; using System.Collections; namespace MyCustomTranslator { public class ReverserEndpoint : ITranslateEndpoint { // 端点的唯一ID用于在配置文件中指定 [Endpoint] 节 public string Id Reverser; // 在插件GUI中显示的名称 public string FriendlyName 文本反转器; // 最大并发请求数对于本地端点可以设高 public int MaxConcurrency 10; // 每次请求最大翻译文本数本例为简单处理一次一个 public int MaxTranslationsPerRequest 1; // 初始化方法可以读取配置 public void Initialize(IInitializationContext context) { // 可以从插件的Config.ini中读取自定义配置节 // bool mySetting context.GetOrCreateSetting(Reverser, MyConfig, true); // 这里我们不需要特殊配置 } // 核心翻译方法 public IEnumerator Translate(ITranslationContext context) { // 获取待翻译文本 string original context.UntranslatedText; // 执行“翻译”将字符串反转 char[] charArray original.ToCharArray(); System.Array.Reverse(charArray); string reversedText new string(charArray); // 调用Complete表示翻译成功并传入结果 context.Complete(reversedText); // 因为是即时完成的没有异步操作所以返回null return null; } } }编译后将生成的MyCustomTranslator.dll放入游戏的BepInEx/plugins/XUnity.AutoTranslator/Translators/目录。重启游戏在翻译端点选择列表中你就能看到“文本反转器”选项。选择它游戏内所有文本都会被反转显示。这个例子虽然简单但清晰地展示了实现一个端点所需的全部要素ID、名称、并发控制、初始化和翻译逻辑。5.2 利用Resource Redirector进行资源替换假设我们想开发一个Mod将游戏内所有“药水”的图标替换成自定义的图标。我们可以利用XUA内置的Resource Redirector库来实现而无需依赖完整的AutoTranslator。首先在你的Mod插件项目中引用XUnity.Common.dll和XUnity.ResourceRedirector.dll。using UnityEngine; using XUnity.ResourceRedirector; public class MyPotionReplacerPlugin { public void Awake() { // 注册资源加载后的回调后置钩子 ResourceRedirection.RegisterAssetLoadedHook( HookBehaviour.OneCallbackPerResourceLoaded, 100, // 优先级 OnAssetLoaded); } private void OnAssetLoaded(AssetLoadedContext context) { // 1. 检查加载的资源类型是否为Texture2D图片 if (!(context.Asset is Texture2D texture)) return; // 2. 获取资源的唯一路径标识用于判断是否是我们要替换的资源 string assetPath context.GetUniqueFileSystemAssetPath(texture); // 3. 假设我们知道“药水”图标的内部路径或名称特征 // 这里用名称包含potion作为示例实际中可能需要更精确的匹配 if (assetPath.ToLower().Contains(potion)) { // 4. 加载我们准备好的替换纹理 // 假设我们的替换图片放在Mod目录下的 Textures/my_cool_potion.png string modPath Path.Combine(Paths.PluginPath, MyPotionMod/Textures/my_cool_potion.png); if (File.Exists(modPath)) { byte[] fileData File.ReadAllBytes(modPath); Texture2D newTexture new Texture2D(2, 2); newTexture.LoadImage(fileData); // 自动识别PNG/JPG等格式 // 5. 替换资源 context.Asset newTexture; // 6. 通知Resource Redirector我们已完成处理并跳过后续的其他后置钩子 context.Complete(skipRemainingPostfixes: true); Debug.Log($已替换药水纹理: {assetPath}); } } // 如果不是我们要替换的资源什么都不做让资源正常加载 } }这个Mod在游戏加载任何纹理资源时都会检查如果路径包含“potion”就用我们自定义的图片替换它。Resource Redirector的API非常强大你可以在资源加载前Prefix就决定加载另一个文件也可以在加载后Postfix修改资源对象。这为游戏资源Mod开发打开了无限可能。6. 局限性与未来展望尽管XUnity.AutoTranslator功能强大但它并非万能也存在一些固有的局限性。对IL2CPP的支持仍在完善IL2CPP是Unity的一种将C#代码预编译为C的先进后端能提升性能和安全性但也使得传统的运行时代码注入Hook变得困难。XUA对IL2CPP游戏的支持度相对Mono游戏要低例如TextGetterCompatibilityMode和IMGUI翻译可能无法使用文本钩子的稳定性也可能稍差。虽然项目提供了BruteForceFix等辅助方案但兼容性仍需针对每个游戏进行测试和调整。性能与稳定性权衡开启纹理翻译、全场景纹理扫描、高精度哈希计算FromImageData等功能会显著增加内存和CPU开销在配置较低的机器上可能导致卡顿。复杂的正则表达式和大量翻译条目的实时匹配也会消耗计算资源。因此在追求完美翻译和保持游戏流畅之间需要做出权衡。翻译质量依赖外部服务其核心的自动翻译质量完全取决于后端翻译引擎Google、DeepL等。对于游戏特有的术语、俚语、文化梗机器翻译往往力不从心甚至闹出笑话。这也是为什么高质量的翻译包离不开人工校对和创建大量“替换规则”Substitutions的原因。未来这个项目的发展方向可能会集中在对IL2CPP更好的原生支持随着Unity新项目越来越多地使用IL2CPP社区对这方面稳定性的需求会越来越强。集成本地大语言模型LLM随着像Llama、Qwen等开源LLM模型在本地部署变得可行未来可能会出现直接调用本地LLM进行翻译的端点在保护隐私的同时获得比传统统计机器翻译更准确、更符合语境的译文。更智能的上下文翻译目前的翻译基本是单句进行。如果能结合游戏对话历史、角色信息等上下文翻译质量有望进一步提升。这可能需要更深入的插件与游戏逻辑的集成。社区翻译平台集成或许未来能出现一个中心化的平台玩家可以上传和共享针对特定游戏的、经过人工校对的翻译缓存文件_AutoGeneratedTranslations.txt甚至包括处理好的UI重缩放规则和纹理包形成真正的“即插即用”高质量翻译社区生态。从我个人的使用经验来看XUnity.AutoTranslator已经远远超出了一个“翻译插件”的范畴。它是一个桥梁连接了玩家与外语游戏连接了Mod开发者与游戏内部资源更连接了自动化工具与人工精校的智慧。它的模块化设计和开放的API使其成为了Unity游戏Modding领域的一个基础设施级别的项目。无论你是想无障碍畅玩一款小众佳作还是想为爱发电制作一个精良的汉化包亦或是想开发一个改变游戏资源的Mod深入理解并善用这个工具都将让你事半功倍。