1. 项目概述为什么你需要XUnity.AutoTranslator如果你是一名热爱日系或独立游戏的玩家或者是一位需要本地化测试的开发者那么你大概率遇到过这个痛点面对一款没有官方中文、但剧情和系统又极其吸引人的Unity游戏只能对着满屏的外文干瞪眼。传统的汉化补丁需要等待汉化组发布周期长且不一定适配你的游戏版本。而XUnity.AutoTranslator以下简称XUA的出现彻底改变了这个局面。它不是一个简单的文本替换工具而是一个运行在游戏进程内、能够实时拦截并翻译游戏内文本的插件系统。简单来说XUA就像给你的游戏安装了一个“同声传译”。游戏运行时每当有新的文本比如对话、UI按钮、物品描述被渲染到屏幕上XUA就会立刻捕获这段文本将其发送到你配置的翻译服务如谷歌翻译、百度翻译、DeepL等获取翻译结果后再无缝替换掉原来的文本显示出来。整个过程几乎是实时的你可以在游戏进行中随时开启或关闭翻译默认快捷键ALTT也可以手动编辑自动生成的翻译文件实现更精准的本地化。这个插件的强大之处在于其深度集成与高度可定制性。它不修改游戏原始文件而是通过Hook钩子技术动态修改游戏内存中的数据流因此理论上兼容所有基于Unity引擎的游戏无论是Steam上的独立佳作还是一些小型社团制作的Galgame。对于玩家它提供了“开箱即用”的实时机翻体验对于进阶用户和汉化爱好者它提供了一整套从文本捕获、翻译、缓存到手动修正的完整工具链。接下来我将带你从零开始彻底掌握这个强大工具。2. 核心工作流程与架构拆解要理解XUA如何工作我们需要深入到它的架构层面。它并非一个单一模块而是一个由多个协同工作的组件构成的生态系统。2.1 核心组件与数据流XUA的核心工作流可以概括为“拦截-查询-替换-渲染”四个步骤。其核心依赖于两个基础库XUnity.Common.dll提供通用功能和兼容层XUnity.ResourceRedirector.dll负责底层资源重定向这是实现文本和纹理替换的基石。AutoTranslator插件本身则构建在这两个库之上负责翻译逻辑。文本拦截Hook当游戏调用Unity的UI组件如UGUI的Text、TextMeshPro来设置文本内容时XUA通过Harmony或MonoMod等注入库将游戏对Text.text或TMP_Text.text属性的赋值操作“拦截”下来。此时游戏原本要显示的原始文本如日文“こんにちは”被XUA捕获。翻译查询Translation Lookup捕获到文本后XUA首先检查本地翻译缓存。这个缓存位于BepInEx/plugins/XUnity.AutoTranslator/Translation/{目标语言}/Text/目录下主要是_AutoGeneratedTranslations.txt文件以及你手动创建的其他.txt文件。如果在缓存中找到了该原文的翻译则直接使用。在线翻译Online Translation如果缓存中没有命中且用户配置了在线翻译端点EndpointXUA会将文本发送到对应的翻译API。为了减少请求次数和提升体验插件会进行“批处理”Batching将短时间内出现的多个短句合并为一个请求发送。翻译返回的结果会被自动写入_AutoGeneratedTranslations.txt文件形成新的缓存。文本替换与渲染Replacement Rendering获得翻译文本后XUA会将其设置回UI组件替换掉原始文本。这里涉及一个关键问题翻译后的文本长度很可能与原文不同。为此XUA提供了自动UI重排功能EnableUIResizing它会尝试调整文本框的溢出模式、字体大小甚至行间距以确保翻译后的文本能够正确显示不会因为显示区域不够而被截断。2.2 配置文件控制一切的枢纽XUA的所有行为都由一个名为Config.ini的配置文件控制。这个文件通常位于BepInEx/config/AutoTranslatorConfig.ini。理解并正确配置这个文件是玩转XUA的关键。配置文件采用INI格式分为多个区块Section。[General]区块这是最核心的配置区。Language目标翻译语言例如zh-CN简体中文、en英文。Endpoint翻译服务提供商。这是最重要的设置之一决定了使用哪个在线翻译。例如GoogleTranslate谷歌翻译、BaiduTranslate百度翻译、DeepLTranslateDeepL等。如果留空或设置为None则只使用本地缓存文件不进行在线翻译。MaxCharactersPerTranslation单次翻译请求的最大字符数。这是一个非常重要的安全与合规设置。官方文档明确警告禁止在分发整合包时将此值设置为大于400。这是为了防止滥用翻译API给服务商造成过大负荷。个人使用时也应保持合理设置通常1000以内是安全的。EnableTranslation总开关设为False可完全禁用翻译功能。[Behaviour]区块控制插件的高级行为。EnableBatching是否启用请求批处理。强烈建议开启True它能将多个短句合并请求显著提升翻译速度并减少API调用次数。EnableUIResizing和ForceUIResizing控制UI自动重排。EnableUIResizing是智能模式只在需要时调整ForceUIResizing是强制模式始终调整。对于UI布局复杂的游戏可能需要开启后者。TextGetterCompatibilityMode一个关键的兼容性开关。如果开启翻译后游戏出现功能异常、卡死或逻辑错误例如某些选项无法点击请尝试将此选项设为True。这会让插件“欺骗”游戏让游戏逻辑检测到的文本仍然是原文而仅修改显示给玩家的文本。[Texture]区块控制图像翻译替换功能。EnableTextureTranslation是否启用图像替换。例如将游戏内的日文图片按钮替换为中文图片。EnableTextureDumping是否启用图像导出。开启后游戏运行时遇到的纹理图片会被导出到TextureDirectory指定的文件夹。注意切勿在公开发布的整合包中开启此选项因为这可能涉及游戏资源的版权问题。TextureHashGenerationStrategy图像哈希生成策略。推荐使用FromImageName基于内部资源名性能最好。如果出现图片无法替换或替换错误可尝试FromImageData基于图像数据但会消耗更多性能。实操心得配置文件备份与版本管理在开始深度调整配置前我强烈建议你先复制一份原始的Config.ini文件作为备份。因为XUA的配置项繁多一旦改错可能导致插件无法正常工作。此外当你更新XUA插件版本时新版本可能会在配置文件中添加新的选项。更新后最好用新版本的默认配置文件与你修改过的旧配置文件进行对比合并而不是直接覆盖以免丢失你精心调整的设置。3. 从零开始安装、配置与初体验理论说得再多不如亲手实践。下面我们以最常见的Mod管理器BepInEx为例演示完整的安装与配置流程。3.1 环境准备与插件安装安装BepInEx首先确保你的目标Unity游戏已经安装了BepInEx。大多数现代Unity游戏Mod都依赖它。如果游戏没有你需要先寻找适用于该游戏版本的BepInEx安装包通常是一个压缩包解压后将BepInEx文件夹整体放入游戏根目录即与游戏主程序.exe文件同级。下载XUnity.AutoTranslator前往GitHub的发布页面下载对应BepInEx 5.x版本的插件包文件名通常为XUnity.AutoTranslator-BepInEx-5.x-{版本号}.zip。安装插件将下载的ZIP包解压你会看到类似BepInEx的文件夹结构。直接将解压出的BepInEx文件夹拖拽到游戏根目录与现有的BepInEx文件合并。通常需要合并plugins和patchers文件夹。验证安装启动游戏。如果安装成功游戏启动时在后台会初始化XUA。你可以在游戏根目录的BepInEx/plugins/XUnity.AutoTranslator下看到生成的Translation文件夹和日志文件。3.2 首次运行与基础配置首次运行游戏后XUA会生成默认的Config.ini文件。关闭游戏用记事本或任何代码编辑器打开BepInEx/config/AutoTranslatorConfig.ini。我们需要进行几项关键配置设置目标语言找到[General]区块下的Language项将其改为zh-CN简体中文。如果你想翻译成英文则改为en。选择翻译服务Endpoint这是核心步骤。找到[General]区块下的Endpoint项。默认可能是空或GoogleTranslate。你需要根据网络环境和需求选择GoogleTranslate通用性强质量尚可。但在某些地区可能需要特殊网络配置。注意配置文件中有一个[Google]区块其中ServiceUrl项绝对不要用于任何非官方或不合规的用途应保持为空。BaiduTranslate国内访问稳定需申请API。在[Baidu]区块下填写BaiduAppId和BaiduAppSecret。DeepLTranslate翻译质量公认较高但有速率限制和收费门槛。需要在[DeepLLegitimate]区块填写ApiKey。其他如YandexTranslate、LingoCloud等均需配置相应API密钥。对于新手如果不想配置API可以暂时使用GoogleTranslate确保网络通畅或直接留空仅使用后续的手动翻译功能。调整基础行为在[Behaviour]区块建议将EnableBatching设为True以提升效率。如果游戏UI复杂可以尝试将EnableUIResizing也设为True。保存配置文件重新启动游戏。进入游戏后尝试触发一些对话或打开菜单。如果配置正确你应该能看到游戏内的文本逐渐被替换成中文。首次翻译某个句子时会有短暂延迟正在请求在线翻译之后再次出现同一句子则会瞬间显示读取本地缓存。3.3 热键操作与实时控制XUA提供了丰富的热键让你在游戏过程中能灵活控制ALT0打开翻译端点选择菜单。你可以随时切换不同的在线翻译服务或者选择“空”来完全禁用在线翻译仅使用本地缓存。ALTT全局翻译开关。这是最常用的热键可以一键开启或关闭所有文本的实时翻译。当翻译导致UI错乱或你想看原文时非常有用。ALTR重新加载翻译文件。当你手动编辑了_AutoGeneratedTranslations.txt或其他翻译文件后无需重启游戏按下此键即可立即生效。CTRLALTNP7在控制台输出当前加载的场景ID等信息用于高级的翻译范围限定Scoping调试。掌握这几个热键你就能在游戏过程中游刃有余地管理翻译状态了。4. 进阶实战手动翻译、字体与UI优化自动翻译虽然方便但机翻的质量参差不齐尤其是对于游戏专有名词、角色语气、双关语等往往词不达意。这时手动翻译和精细化调整就派上用场了。4.1 创建与编辑手动翻译文件XUA会将其翻译的所有文本记录在Translation/{Lang}/Text/_AutoGeneratedTranslations.txt中。这个文件是自动生成的不建议直接大规模修改它因为插件重启后可能会重新生成或覆盖。正确的做法是创建独立的手动翻译文件在Translation/zh-CN/Text/目录下以中文为例新建一个文本文件例如MyManualTranslations.txt。打开_AutoGeneratedTranslations.txt找到翻译质量不佳的句子。复制整行格式为原文翻译。例如騎士団長骑士团长 これは、わたしの必殺技だ这就是我的必杀技将复制的内容粘贴到你的MyManualTranslations.txt中并修改等号右侧的翻译为你满意的版本。保存文件在游戏中按下ALTR重新加载翻译。XUA会优先读取手动翻译文件中的条目只有当手动文件中找不到时才会使用_AutoGeneratedTranslations.txt中的自动翻译或发起在线请求。你可以按游戏章节、系统功能创建多个文件方便管理。4.2 解决字体显示问题中文字体缺失很多日文或英文游戏自带的字体不包含中文字符集导致翻译成中文后显示为方框“□□□”。XUA提供了字体覆盖功能来解决此问题。获取字体文件你需要一个包含中文字符的.ttf或.otf字体文件例如“思源黑体”、“方正准圆”等。注意版权确保用于个人修改。创建字体AssetBundle针对UGUI这是比较复杂的步骤。你需要使用与游戏相同版本的Unity Editor将字体文件导入创建TextMeshPro Font Asset并将其打包成AssetBundle。网上有相关教程。对于大多数玩家更简单的方法是寻找社区分享的、针对特定游戏或通用版本的字体AssetBundle包。配置字体覆盖将制作好的字体AssetBundle文件例如chinese_font.bundle放入游戏根目录。然后在Config.ini的[Behaviour]区块进行配置对于UGUI设置OverrideFontchinese_font无需后缀名。插件会尝试加载chinese_font.bundle。对于TextMeshPro (TMP)更推荐使用FallbackFontTextMeshPro选项。将字体AssetBundle放入游戏目录后设置FallbackFontTextMeshProchinese_font。这样当游戏原字体缺少某个中文字符时会自动回退到你指定的字体。避坑指南字体加载失败如果配置后字体没有生效首先检查游戏使用的是UGUI还是TextMeshPro。可以通过游戏目录下是否存在TextMeshPro文件夹或相关DLL来判断。其次确认AssetBundle使用的Unity版本与游戏一致。最后查看BepInEx/LogOutput.log日志文件搜索字体加载相关的错误信息这是排查问题的第一手资料。4.3 高级UI调整使用Resizer文件当翻译文本过长导致显示不全时除了开启自动重排还可以进行像素级的手动调整。这需要用到resizer.txt文件。启用路径日志在Config.ini中设置[Behaviour]下的EnableTextPathLoggingTrue。获取UI路径启动游戏触发你想要调整的那个文本显示比如一个过长的物品描述。然后查看日志文件你会找到类似这样的输出Text path: Canvas/Panel/ItemSlot/DescriptionText。创建调整规则在Translation/zh-CN/Text/目录下创建一个文件命名为ui_resizer.txt名字任意后缀为.txt即可。在其中写入规则Canvas/Panel/ItemSlot/DescriptionTextChangeFontSizeByPercentage(0.8);AutoResize(true, 10, 24)这条规则的意思是对于路径为Canvas/Panel/ItemSlot/DescriptionText的文本组件将其字体大小调整为原来的80%并启用自动重排最小字体为10最大为24。保存文件按ALTR重载。你会发现该处的文本自动调整了大小以适应框体。通过组合不同的命令如UGUI_HorizontalOverflow、TMP_Alignment等你可以精细控制几乎所有UI文本的渲染行为。5. 开发者视角插件集成与资源重定向XUA不仅是一个玩家工具也为Unity游戏Mod开发者提供了强大的API允许其他插件与其交互甚至实现自定义的翻译逻辑和资源替换。5.1 为你的Mod添加翻译支持如果你在开发一个为游戏添加新内容如新物品、新任务的Mod你可以让这些新内容也支持XUA的翻译体系。方法一插件特定翻译目录在你的Mod的翻译目录下例如Translation/zh-CN/Text/Plugins/创建一个以你的Mod的DLL命名的文件夹不含.dll扩展名。在这个文件夹里放置你的翻译文件。XUA会优先读取这个目录下的翻译避免与全局翻译冲突。你还可以在翻译文件中加入#enable fallback指令允许在找不到特定翻译时回退到全局翻译。方法二通过代码API注册在你的Mod插件初始化时例如在Start()方法中调用XUA提供的TranslationRegistryAPI来动态注册翻译。public void Start() { // 假设你有一个包含翻译键值对的Stream Stream translationStream GetYourTranslationStream(); var package new StreamTranslationPackage(translationStream); // 注册到当前程序集 TranslationRegistry.Default.RegisterPluginSpecificTranslations( Assembly.GetExecutingAssembly(), package ); // 允许回退到全局翻译 TranslationRegistry.Default.EnablePluginTranslationFallback(Assembly.GetExecutingAssembly()); }这种方式更灵活可以将翻译资源直接嵌入到Mod的DLL中无需玩家额外管理文件。5.2 阻止XUA翻译你的Mod UI有时你的Mod UI可能不需要或不想被XUA翻译例如代码编辑器、调试信息面板。XUA提供了两种方式来屏蔽对于GameObject-based UIUGUI/TMP将包含Text组件的GameObject名称设置为包含XUAIGNORE字符串。XUA在创建组件时会检查此名称并跳过。如果命名为XUAIGNORETREE则会忽略该GameObject下所有子对象的文本组件。对于IMGUIOnGUI在你的OnGUI方法中通过查找XUA的GameObject并发送消息来临时禁用翻译。private GameObject _xua; private bool _lookedForXua; public void OnGUI() { if(!_lookedForXua) { _lookedForXua true; _xua GameObject.Find(___XUnityAutoTranslator); } try { _xua?.SendMessage(DisableAutoTranslator); // 绘制你的IMGUI控件 GUILayout.Label(This will NOT be translated.); } finally { _xua?.SendMessage(EnableAutoTranslator); } }try-finally块确保即使你的GUI代码抛出异常翻译功能也会被重新启用。5.3 深入资源重定向修改游戏内任意资源XUA内置的Resource Redirector库是一个更底层的强大工具它允许Mod开发者拦截和替换游戏通过Resources.Load或AssetBundle加载的任何资源而不仅仅是文本。例如你可以替换游戏内的音频、纹理、模型甚至整个Prefab。其核心是注册钩子Hook到加载过程。示例替换一个纹理public class MyTextureRedirector : XPluginBase { public void Awake() { // 注册资源加载后的钩子Postfix Hook ResourceRedirection.RegisterResourceLoadedHook( HookBehaviour.OneCallbackPerResourceLoaded, 100, // 优先级 OnTextureLoaded ); } private void OnTextureLoaded(ResourceLoadedContext context) { // 检查加载的资源是否是纹理并且路径符合要求 if(context.Asset is Texture2D tex context.Parameters.Path.EndsWith(MyTargetTexture.png)) { // 加载你自己的纹理 Texture2D myTexture LoadMyCustomTexture(); // 替换游戏原本要加载的纹理 context.Asset myTexture; context.Complete(skipRemainingPostfixes: true); } } }通过这个机制Mod开发者可以实现深度的游戏内容自定义远超文本翻译的范畴。XUA的文本翻译功能本身就是基于这个Resource Redirector库对TextAsset资源进行拦截和替换实现的。6. 疑难杂症排查与性能调优即使配置正确在实际使用中也可能遇到各种问题。这里汇总了一些常见故障及其解决方法。6.1 常见问题速查表问题现象可能原因解决方案游戏启动崩溃或黑屏BepInEx或XUA版本与游戏不兼容与其他Mod冲突。1. 确认BepInEx版本匹配游戏框架Mono/IL2CPP。2. 尝试纯净环境只保留BepInEx和XUA启动。3. 查看BepInEx/LogOutput.log末尾的错误信息。翻译完全不生效插件未正确加载配置文件中EnableTranslationFalseEndpoint未设置或网络不通。1. 检查日志确认XUA插件已加载。2. 检查Config.ini中[General]下的EnableTranslation和Endpoint。3. 按ALT0查看翻译端点菜单是否弹出。翻译生效但显示为方框“□”游戏字体不支持目标语言字符。1. 配置字体覆盖OverrideFont或FallbackFontTextMeshPro。2. 确保字体AssetBundle兼容游戏Unity版本。翻译后游戏逻辑出错如选项无法点击游戏代码通过检查显示的文本来决定逻辑。在Config.ini中设置[Behaviour]-TextGetterCompatibilityModeTrue。在线翻译速度极慢或失败网络问题API调用频率受限Endpoint配置错误。1. 检查网络连接。2. 确认API密钥有效且未超限额如DeepL免费版。3. 尝试切换其他翻译端点如Baidu。4. 开启EnableBatching减少请求次数。部分UI文本未被翻译文本可能由IMGUI绘制或属于动态生成的组件。1. 尝试开启[Behaviour]-EnableIMGUITrue谨慎可能影响性能。2. 可能是游戏使用了特殊渲染方式XUA支持有限。内存占用过高或游戏变卡启用了纹理翻译或缓存了过多纹理批处理设置不当。1. 关闭[Texture]-CacheTexturesInMemoryFalse。2. 禁用纹理翻译相关功能。3. 检查MaxCharactersPerTranslation是否过大。6.2 性能调优建议XUA作为一个实时注入式插件对性能的影响主要取决于以下几个配置项合理调整可以最大化游戏体验纹理翻译这是最大的性能杀手。除非必要否则保持[Texture]区块下所有选项为False。特别是EnableTextureScanOnSceneLoad和EnableSpriteRendererHooking只在需要替换大量UI图片时开启。翻译批处理务必开启EnableBatchingTrue。这能将数十个短句合并为一个网络请求极大降低延迟和CPU开销。缓存与文件IOCacheMetadataForAllFilesTrue默认有助于提升从ZIP包加载翻译文件的速度。如果你将翻译文件打包成.zip格式放在Translation目录下这个选项能避免重复的文件检查。日志输出在调试完毕后关闭所有调试日志。在Config.ini中设置[Debug]-EnableLogFalse和EnableConsoleFalse除非你需要BepInEx控制台。日志输出会持续写入磁盘影响性能。IL2CPP游戏的特别优化对于使用IL2CPP后端编译的游戏很多现代Unity游戏都是XUA的文本钩子能力可能较弱。可以尝试使用官方提供的AutoTranslator.IL2CPP.BruteForceFix辅助插件来改善。同时避免在这类游戏上使用过于复杂的功能如IMGUI翻译。6.3 日志分析与调试当遇到任何疑难杂症时BepInEx/LogOutput.log文件是你最好的朋友。XUA会在这里输出详细的运行信息。查看插件加载状态搜索“XUnity.AutoTranslator”字样确认插件是否成功加载及其版本号。检查翻译过程开启[Debug]-EnableLogTrue后日志会记录捕获的原文、查询的翻译结果等信息。你可以看到翻译是否成功或者失败的原因如网络超时、API返回错误。定位UI路径如前所述开启EnableTextPathLoggingTrue后所有文本的GameObject路径都会被记录用于手动UI调整。诊断资源重定向开启[ResourceRedirector]-LogAllLoadedResourcesTrue可以记录游戏加载的所有资源路径对于开发高级Mod至关重要。养成在遇到问题时第一时间查看日志的习惯能帮你快速定位问题根源无论是配置错误、网络问题还是插件冲突。