1. 项目概述为什么我们需要XUnity Auto Translator如果你是一个喜欢玩各种独立游戏或者小众Unity游戏的玩家或者你是一个游戏汉化组的成员那么“游戏内置文本无法翻译”这个问题你一定深有体会。游戏开发者可能只发布了英文、日文版本而社区里流传的汉化补丁要么版本老旧要么安装复杂甚至可能因为游戏更新而彻底失效。手动修改游戏文件那更是大海捞针一个现代游戏动辄成千上万个文本资源文件根本无从下手。XUnity Auto Translator以下简称XUAT的出现就是为了解决这个核心痛点。它不是某个特定游戏的汉化补丁而是一个运行时的、通用的文本拦截与替换框架。简单来说它就像是在游戏和你的屏幕之间插入了一个“同声传译员”。游戏引擎Unity在要把一段文本显示到UI上时XUAT会先“听到”这段文本然后立刻去查询你准备好的翻译词典如果找到了对应的翻译它就把翻译后的文本“说”给屏幕听替换掉原来的内容。整个过程对游戏本身是透明的游戏甚至不知道自己的文本被“调包”了。这带来了几个革命性的优势第一是通用性理论上支持所有基于Unity引擎开发的游戏无论是Steam上的独立游戏还是一些小型网页游戏。第二是实时性翻译是即时生效的无需重启游戏。第三是可持续性游戏更新后只要其文本调用逻辑没变原有的翻译文件大概率依然有效大大降低了汉化维护成本。第四是社区友好它催生了一种新的汉化模式由社区维护统一的、基于文本哈希或键名的翻译文件玩家只需下载翻译文件和这个“框架”即可享受汉化汉化组也无需每次都为游戏更新而重做补丁。我接触XUAT已经有好几年从最早的BepInEx插件形式用到现在的独立注入器形式用它成功汉化过数十款游戏。可以说对于Unity游戏翻译这个细分领域XUAT是目前最强大、最灵活的“终极解决方案”没有之一。本手册将带你从零开始彻底掌握它的工作原理、部署方法、配置技巧以及高阶用法让你能轻松应对绝大多数Unity游戏的翻译需求。2. 核心架构与工作原理深度拆解要熟练使用一个工具绝不能停留在“点击安装”的层面。理解XUAT是如何“嵌入”游戏并工作的能让你在遇到问题时快速定位甚至进行一些高级定制。2.1 核心组件与工作流XUAT不是一个单一的exe文件而是一个由多个组件协同工作的系统。典型的部署包含以下部分注入器 (Injector)这是将XUAT“植入”游戏的关键。常见的注入器有BepInEx一个强大的Unity游戏Mod框架。XUAT可以作为它的一个插件Plugin运行。这是最主流、最稳定的方式尤其适用于Steam上的游戏。BepInEx本身通过修改游戏程序集Assembly的加载逻辑来实现注入。UnityInjector/MelonLoader其他流行的Mod加载器原理类似都是通过劫持Unity引擎的初始化过程来加载自定义代码。独立的CLI注入器一些打包好的版本会自带一个小的命令行注入器它通过修改游戏进程的内存或DLL加载顺序来实现注入更适合小白用户一键操作。XUnity.AutoTranslator 核心插件这是翻译逻辑的本体。它被注入器加载后会向Unity引擎的MonoBehaviour生命周期挂载钩子Hook。具体来说它主要监听两类事件UI.Text,TextMeshProUGUI.text属性设置当游戏脚本给任何一个UI文本组件赋值时如someTextComponent.text “Hello World”;XUAT的钩子会先截获这个字符串“Hello World”。Resources.Load等资源加载调用有些游戏文本可能直接存储在.assets资源文件中通过Unity的API加载。XUAT也能拦截这些调用检查加载的资源是否包含文本。翻译引擎 (Translator)核心插件截获原文后需要知道把它翻译成什么。XUAT支持多种后端翻译服务形成一个可插拔的架构离线词典 (Offline Dictionary)最高优先级。这就是我们常说的“汉化补丁”文件。XUAT会先在本地词典文件中查找原文的对应翻译找到了就直接使用速度快且准确。在线翻译API如果本地词典未命中且配置允许则会调用在线服务。它内置支持谷歌翻译、百度翻译、DeepL等需要自行配置API密钥。在线翻译的优点是能覆盖未翻译的新文本缺点是可能有延迟、需要网络并且有调用频率限制。缓存 (Cache)无论是离线词典还是在线翻译的结果都会被保存到本地缓存文件通常是Translation.txt。下次游戏再遇到同一句原文时就直接从缓存读取无需再次查询极大提升性能并减少在线API调用。翻译文件 (Translation Files)这是汉化工作的成果载体。XUAT主要使用一种简单的keyvalue格式的文本文件如Translation.txt。键 (Key)可以是原文本身也可以是原文经过哈希如SHA-256计算后的一串唯一标识符。使用哈希值作为键可以避免因原文中细微的标点、空格差异导致翻译失效兼容性更好。值 (Value)就是对应的翻译文本。整个工作流可以概括为注入 - 拦截 - 查询先离线后在线- 替换 - 缓存。这个过程在每帧可能发生成千上万次但对性能的影响微乎其微因为核心的查找操作经过高度优化。2.2 关键技术点挂钩Hooking与反射ReflectionXUAT实现文本拦截的核心技术是“挂钩”。在.NETUnity使用的C#环境中这通常通过修改方法在内存中的地址使其跳转到我们自定义的代码来实现。但更常见和稳定的方式是使用“Harmony”这类库。Harmony可以在运行时对已编译的方法打上“补丁”Patch在其执行前、后或完全替换其执行逻辑。XUAT就是利用Harmony给Unity的Text.set_text属性设置器打上“前置补丁”Prefix Patch从而在游戏设置文本之前先拿到这个文本值。为了兼容不同版本Unity的UI系统如旧的uGUI Text和新的TextMeshProXUAT需要用到“反射”Reflection来动态探测和访问游戏程序集中的类型和方法。例如它会在游戏启动时检查程序集中是否存在TMPro.TextMeshProUGUI这个类如果存在则通过反射获取其text属性并为其打上挂钩。这种动态特性使得XUAT能够适应大量不同游戏而无需为每个游戏单独编译。注意正是由于这种底层注入和挂钩机制杀毒软件或Windows Defender可能会误报注入器或插件文件为病毒或潜在不受欢迎的程序PUP。在使用前务必将相关工具和游戏目录添加到杀毒软件的白名单中否则文件可能会被误删导致注入失败。3. 完整部署与配置实战指南理论讲完我们进入实战环节。我将以最常用的“BepInEx XUAT插件”组合为例详细讲解从零部署的全过程。假设我们要翻译的游戏是MyUnityGame.exe。3.1 环境准备与工具选择确认游戏信息找到游戏主程序MyUnityGame.exe右键“属性”-“详细信息”查看文件版本和产品名称。用记事本打开MyUnityGame_Data/Managed/Assembly-CSharp.dll如果有的话可以确认游戏使用的.NET框架版本通常为.NET 3.5/4.x这关系到BepInEx版本的选择。下载必要工具BepInEx去GitHub发布页下载。对于大多数Unity游戏选择BepInEx x64版本如果游戏是32位则选x86。下载后是一个压缩包如BepInEx_unity_win_x64_5.4.22.0.zip。XUnity.AutoTranslator去官方发布页如GitHub下载。你需要两个文件XUnity.AutoTranslator-BepInEx-5.4.22.zip核心插件和XUnity.AutoTranslator-Japanese-5.4.22.zip这是一个示例包含日语翻译和在线翻译插件我们主要需要其中的在线插件。注意版本号尽量与BepInEx匹配。3.2 逐步安装与注入流程安装BepInEx解压BepInEx压缩包将其中的所有文件和文件夹复制到游戏根目录即MyUnityGame.exe所在目录。首次运行游戏。双击MyUnityGame.exe启动游戏等待游戏完全启动到主菜单后再关闭。这个过程会让BepInEx完成初始安装在游戏根目录下生成完整的BepInEx文件夹结构包括plugins,config,core等子目录。安装XUAT插件解压XUnity.AutoTranslator-BepInEx-5.4.22.zip将其中的BepInEx文件夹合并到游戏根目录的BepInEx文件夹中。通常是plugins和config目录下的内容会被合并进去。解压XUnity.AutoTranslator-Japanese-5.4.22.zip我们主要需要其中的BepInEx/plugins/AutoTranslator/Translation文件夹可以删除里面的日语翻译文件和BepInEx/plugins/AutoTranslator/Plugins文件夹里面包含了在线翻译所需的插件如GoogleTranslateBaiduTranslate等。同样合并到游戏目录。关键目录结构确认 安装完成后你的游戏BepInEx目录下应该有以下关键结构BepInEx/ ├── plugins/ │ └── XUnity.AutoTranslator/ │ ├── AutoTranslator.dll (核心插件) │ ├── Plugins/ (在线翻译插件目录) │ │ ├── GoogleTranslate.dll │ │ ├── BaiduTranslate.dll │ │ └── ... │ └── Translation/ (翻译文件目录) │ ├── en/ (示例英文翻译目录) │ ├── zh/ (中文翻译目录 - 需自建) │ ├── Translation.txt (主缓存文件) │ └── Substitutions.txt (文本替换规则文件) ├── config/ (配置文件目录) │ └── AutoTranslatorConfig.ini (XUAT主配置文件) └── core/ (BepInEx核心)3.3 核心配置文件详解BepInEx/config/AutoTranslatorConfig.ini是XUAT的大脑所有行为都由它控制。用记事本或VS Code打开它我们来调整关键参数。[General] ; 目标语言设为中文 Languagezh ; 是否启用在线翻译当你没有离线翻译时可以临时开启 EnableTranslation true ; 是否将在线翻译结果自动保存到离线词典 AppendTranslationsToFiletrue ; 离线词典文件名 TranslationFileNameTranslation.txt [Behaviour] ; 是否在游戏启动时预加载所有翻译到内存建议开启以提升性能 PreloadTranslationstrue ; 是否翻译资源文件如.assets中的文本建议开启 TranslateResourcestrue ; 是否翻译Unity场景中的GameObject名称按需开启 TranslateGameObjectNamesfalse [TextFrameworks] ; 启用对旧版uGUI Text的支持 EnableTexttrue ; 启用对TextMeshPro的支持现代游戏必备 EnableTextMeshProtrue [Online] ; 选择在线翻译引擎可选GoogleTranslate, BaiduTranslate, DeepL等 EnabledTranslatorGoogleTranslate ; 在线翻译失败后的重试次数 MaxTranslationsPerSecond3 [GoogleTranslate] ; 谷歌翻译需要配置但通常有默认端点国内可能需要特殊配置 ; 百度翻译需要申请API Key和Secret Key ;[BaiduTranslate] ;AppId你的AppId ;Secret你的Secret关键配置解析Languagezh这是最重要的设置告诉插件你的目标语言是中文。插件会根据这个值去寻找Translation/zh/目录下的翻译文件。AppendTranslationsToFiletrue强烈建议开启。当在线翻译成功时会自动将原文译文追加到Translation.txt中。这是积累和创建离线汉化补丁的“自动化流水线”。PreloadTranslationstrue开启后游戏启动时会一次性将所有Translation.txt内容加载到内存字典中。对于翻译条目数上万的大型游戏这能避免游戏运行时频繁读盘造成的卡顿。EnabledTranslator如果你需要使用在线翻译请确保对应的插件DLL文件存在于Plugins文件夹并在此正确填写名称。使用百度/谷歌翻译需要自行申请API密钥并配置。3.4 翻译文件的创建与管理离线翻译是汉化质量的保证。我们需要在BepInEx/plugins/XUnity.AutoTranslator/Translation/下创建zh文件夹如果不存在然后创建或编辑翻译文件。主翻译文件 (Translation.txt) 这个文件可以放在Translation/根目录下对所有语言生效也可以放在Translation/zh/下仅对中文生效。推荐后者便于管理。文件格式非常简单Hello你好 Start Game开始游戏 Options选项 Player Health: %d玩家生命值%d格式要点每行一条格式为原文译文。原文和译文中的等号需要用反斜杠转义如Key\Value键\值。支持C风格的格式说明符如%s,%d译文必须保留相同的占位符且顺序一致。原文可以是哈希值。当Translation.txt中某行的键是一串长长的十六进制数如a1b2c3...时说明这是原文的哈希。你不需要自己计算XUAT在自动追加在线翻译结果时就会使用哈希键这能提高兼容性。文本替换文件 (Substitutions.txt) 这个文件用于进行简单的正则表达式替换通常在翻译之前进行用于修正一些常见的原文问题。例如游戏原文可能有奇怪的换行符\n影响翻译或者你想先统一某些术语。patternreplacement示例将所有HP替换为生命值\bHP\b生命值如何高效制作翻译文件“偷懒”法配置好在线翻译后进入游戏把所有UI界面点一遍把所有对话剧情过一遍。XUAT会自动将所有拦截到的、未翻译的文本通过在线API翻译并追加到Translation.txt中。然后你关闭在线翻译基于这个自动生成的、但可能生硬的Translation.txt进行人工校对和润色。这是最快捷的起步方式。专业法使用专门的游戏文本提取工具如UnityEX,AssetStudio直接解包游戏的资源文件提取出所有字符串在外部用CAT计算机辅助翻译工具如Poedit, OmegaT进行翻译和校对最后整理成Translation.txt格式。这种方法质量最高适合汉化组协作。4. 高级技巧与疑难问题排查掌握了基础部署你已经能解决80%的问题。下面这些高级技巧和排错经验能帮你攻克剩下的20%难题。4.1 应对特殊游戏与兼容性调整不是所有Unity游戏都“乖乖就范”。以下是一些常见特殊情况及处理方案游戏使用了IL2CPP后端 IL2CPP是Unity的一种编译技术它将C#代码转换成C再编译为本地机器码这使得传统的基于Mono的注入和挂钩方式失效。对于IL2CPP游戏BepInEx有一个专门的版本BepInEx Il2Cpp。XUAT也有对应的Il2Cpp版本插件。你需要确认游戏是否为IL2CPP看游戏目录是否有GameName_Data/il2cpp_data文件夹。下载BepInEx Il2Cpp版本和XUAT for Il2Cpp版本的插件。安装流程类似但配置可能更复杂可能需要手动配置函数签名来挂钩。游戏文本在纹理图片中 XUAT只能拦截文本如果游戏的所有文字都是图片格式例如一些复古风格的RPG那么它无能为力。这种情况需要传统的“图改”汉化使用PS等工具修改游戏贴图文件。翻译不生效或部分生效检查日志BepInEx会在BepInEx/LogOutput.log中生成运行日志。打开日志文件搜索“AutoTranslator”或“XUnity”查看是否有加载成功、挂钩成功的信息以及翻译查询的记录。这是最强大的排错工具。检查文本组件类型有些游戏使用自定义的文本渲染组件而非标准的Text或TextMeshProUGUI。你需要检查游戏使用的具体组件类型。可以尝试在配置文件中启用EnableNGUI如果游戏使用NGUI或EnableuGUI这是默认。更复杂的情况可能需要手动编写补丁插件。检查文本更新方式极少数游戏可能通过直接设置顶点或材质的方式来“画”出文字这种动态生成的方式无法被拦截。4.2 性能优化与翻译质量提升合并与清理Translation.txt 随着在线翻译的不断追加Translation.txt文件会变得巨大且包含大量重复或未使用的条目。你可以使用社区工具如“XUAT Translation Manager”来加载这个文件它会自动合并重复的键相同的原文或哈希。找出那些译文和原文完全相同的无用条目可能是翻译API返回了原文。按字母顺序排序方便查找和编辑。 定期清理能显著减少文件加载时间和内存占用。分模块翻译文件 对于文本量巨大的游戏可以将翻译按功能模块拆分。在Translation/zh/目录下你可以创建多个.txt文件如UI.txt,Items.txt,Dialogue_Chapter1.txt。XUAT会自动加载该目录下所有的.txt文件。这样便于多人协作和版本管理。处理动态文本与变量 游戏文本常常包含变量如“你击杀了 %d 个敌人”。在翻译时必须保留这些格式符的位置和顺序但可以调整其在句子中的位置以适应中文语序。例如英文是%d enemies killed中文可以翻译为击杀了%d个敌人。切记不要丢失或改变格式符的类型如把%d写成%s。文化适配 高质量的翻译不仅仅是字面转换。例如游戏中的笑话、双关语、文化梗需要找到中文中对应的表达或者进行意译。在Substitutions.txt中你可以提前将一些文化专有名词替换为本地化版本。4.3 常见问题速查表下表汇总了使用XUAT过程中最常见的问题、可能原因及解决方案问题现象可能原因排查步骤与解决方案游戏无法启动闪退1. BepInEx版本与游戏不兼容2. XUAT插件版本与BepInEx不匹配3. 杀毒软件拦截1. 尝试更换BepInEx版本如稳定版/测试版2. 确保XUAT插件是为当前BepInEx版本编译的3. 关闭杀毒软件或添加白名单查看LogOutput.log中的错误信息游戏能启动但无任何翻译效果1. 配置文件Language未设置或错误2. 翻译文件路径或名称错误3. 文本挂钩失败1. 检查AutoTranslatorConfig.ini中Languagezh2. 确认翻译文件在Translation/zh/目录下且名为Translation.txt3. 查看日志确认EnableText和EnableTextMeshPro是否针对游戏正确启用部分UI翻译了部分没翻译1. 游戏使用了多种文本组件2. 未翻译的文本是图片3. 动态生成的文本未被拦截1. 检查日志看未翻译文本的组件类型尝试在配置中启用其他框架支持风险高2. 确认是否为图片文字3. 可能是脚本动态拼接的字符串尝试使用在线翻译覆盖或手动在词典中添加完整句子翻译文本出现乱码或问号1. 游戏字体不支持中文2. 翻译文件编码错误1. 需要替换游戏字体或添加中文字体。这是一个高级话题涉及修改游戏资源2. 确保Translation.txt以UTF-8 without BOM编码保存推荐使用Notepad或VS Code编辑并设置编码在线翻译不起作用1. API未配置或配置错误2. 网络问题3. 插件文件缺失1. 检查配置文件中对应翻译引擎如[BaiduTranslate]的AppId和Secret是否正确2. 确认网络通畅某些API可能需要特殊网络环境3. 确认Plugins文件夹下有对应的GoogleTranslate.dll等文件游戏运行时卡顿明显1.PreloadTranslations未开启2.Translation.txt文件过大3. 在线翻译频率过高1. 在配置中设置PreloadTranslationstrue2. 使用工具清理合并Translation.txt3. 调整MaxTranslationsPerSecond降低频率或关闭在线翻译使用纯离线模式5. 从使用者到贡献者参与社区汉化XUAT的魅力在于它建立了一个可持续的社区汉化生态。你不再是一个被动的补丁使用者而是可以轻松成为贡献者。分享你的翻译文件当你为一款游戏精心校对好Translation.txt后可以将其分享到游戏的社区论坛、贴吧或专门的模组网站如ModDB Nexus Mods。在分享时请清晰说明对应的游戏名称及精确版本号。使用的XUAT和BepInEx版本。安装方法。已知问题哪些地方没翻译为什么。协作翻译平台一些大型游戏的汉化社区会使用GitHub、GitLab或自建平台来管理翻译文件。你可以通过提交Pull Request来修正错别字、优化翻译语句或补充新增内容的翻译。版本控制系统能清晰地记录每个人的贡献。反馈与求助如果你遇到无法解决的问题可以到XUAT的官方GitHub仓库的Issues板块搜索或提问。提问时务必附上你的AutoTranslatorConfig.ini关键部分、LogOutput.log中的相关错误片段以及游戏名称版本。清晰的问题描述能极大提高获得帮助的效率。我个人最深的一个体会是XUAT将游戏汉化从一个“黑盒”的、每次更新都要推倒重来的体力活变成了一个“白盒”的、可积累、可协作的数据工程。最大的挑战往往不是工具本身而是如何高效地获取、整理和校对那海量的游戏文本。一旦建立了稳定的工作流比如在线翻译初翻 - 导出整理 - CAT工具校对 - 回填测试你会发现为Unity游戏提供高质量的本地化支持并没有想象中那么困难。最后一个小技巧在测试翻译时善用游戏的“存档/读档”功能可以快速刷新UI文本而无需反复重启游戏这能节省大量的测试时间。