1. 项目概述为什么我们需要XUnity Auto Translator如果你是一名Unity游戏玩家尤其是经常接触那些只有日文或英文原版的小众独立游戏、视觉小说或者RPG Maker作品那么语言障碍绝对是你绕不开的一座大山。看着屏幕上密密麻麻的假名或字母再精彩的剧情和系统也变成了天书。传统的汉化补丁虽然好用但往往“一游一补”制作周期长且游戏一旦更新补丁就可能失效。有没有一种方法能让我们实时、自动地将游戏内的文本翻译成母语甚至还能自定义和修正翻译结果呢XUnity Auto Translator后文简称XUAT就是为解决这个问题而生的革命性工具。它不是一个简单的文本替换器而是一个深度集成到Unity游戏运行时的插件式翻译框架。简单来说它能在游戏运行时“截获”所有即将显示在屏幕上的文本调用你配置的翻译服务如谷歌、百度、DeepL等进行实时翻译并将结果“塞回”游戏UI中显示出来。整个过程几乎是实时的你甚至可以在游戏进行中按ALT0呼出配置界面切换翻译引擎或调整设置。更强大的是它支持手动翻译、正则表达式替换、图片资源替换UI贴图、字体覆盖甚至允许开发者为其编写新的翻译器插件。这意味着你不仅可以享受AI翻译的便利还能像维护一个开源项目一样和社区一起打磨出一份精准的、针对特定游戏的翻译库。无论是想无障碍体验生肉游戏还是为爱发电制作汉化补丁XUAT都提供了一个极其强大和灵活的基础设施。2. 核心机制与工作原理解析要玩转XUAT不能只停留在“安装即用”的层面。理解其核心工作机制能帮助你在遇到各种稀奇古怪的问题时快速定位并解决。它的工作流程可以概括为“拦截-查询-替换-渲染”四个步骤。2.1 文本拦截游戏是如何“说话”的Unity游戏显示文本最终无非通过几种常见的UI组件传统的UnityEngine.UI.TextUGUI、更现代的TextMeshProTMP或者老旧的GUILabelIMGUI。XUAT的核心能力之一就是通过Harmony一个.NET函数钩子库或MonoMod在游戏调用这些组件的文本设置方法如Text.text的setter时进行拦截。当游戏执行到类似myTextComponent.text “こんにちは”;这行代码时XUAT的钩子会先一步被触发。它拿到原始的日文字符串“こんにちは”然后开始自己的处理流程。这个过程对游戏本身是透明的游戏依然认为它设置的是原始文本但最终用户看到的却是被替换后的内容。这种在运行时动态修改程序行为的技术是许多游戏Mod得以实现的基础。2.2 翻译查询缓存优先与多级回退拦截到文本后XUAT并不会每次都傻傻地去调用在线翻译API那样速度慢且容易触发频率限制。它遵循一个高效的查询策略内存缓存首先检查这个文本字符串是否已经被翻译过并缓存在内存中。如果是直接使用缓存结果速度最快。本地翻译文件如果内存缓存未命中则查询加载到内存中的翻译字典。这些字典来自你Translation目录下的所有.txt文件包括自动生成的_AutoGeneratedTranslations.txt和手动创建的翻译文件。XUAT会遍历所有文件寻找完全匹配或经过空白符处理的匹配项。在线翻译服务如果本地文件也没有找到翻译XUAT才会将文本发送到你配置的在线翻译端点Endpoint如Google Translate。收到翻译结果后它会同时做两件事一是将结果返回给游戏进行显示二是将这个新的翻译对原文-译文追加写入到_AutoGeneratedTranslations.txt文件中并更新内存缓存。下次再遇到相同文本就会走第1或第2步了。这个策略的精妙之处在于“学习能力”。你玩得越久本地积累的翻译就越多对在线API的依赖就越少翻译速度也就越快最终形成一个离线的、专属于这款游戏的翻译库。2.3 资源重定向不止于文本XUAT的另一个核心模块是Resource Redirector资源重定向器。这解决了更底层的问题游戏中的文本和图片很多是直接存储在Resources文件夹或AssetBundle文件中的。传统的Mod需要解包、修改、再封包过程繁琐且易失效。Resource Redirector允许你在游戏加载这些资源时动态地将其替换为你准备好的版本。例如文本资源TextAsset游戏可能从一个.txt或.json文件里读取剧情对话。启用EnableTextAssetRedirector后XUAT会将这些文件“dump”导出到本地目录如Translation\zh-CN\RedirectedResources。你直接修改这些导出的文件游戏下次运行时就会加载你修改后的版本而不是原始包内的文件。纹理资源Texture游戏UI中的图标、按钮图片可能包含文字。通过启用纹理翻译EnableTextureTranslationXUAT可以导出这些图片让你用PS等工具将其P成中文版再放回指定目录游戏运行时就会显示中文图片。这个机制实现了非侵入式的资源修改你无需动游戏的原始资产包所有修改都在外部目录完成干净且易于管理。2.4 空白符与查找逻辑为什么翻译有时不生效这是新手最容易困惑的地方。游戏里显示的同一句对话在代码层面可能有细微差别比如换行符\n的位置、首尾空格等。XUAT为了最大化匹配成功率采用了智能的空白符处理策略。当它遇到一个待翻译文本时会进行多达四次的查找尝试顺序如下原始文本包含所有空白符。去除首尾空白符后的文本。如果找到匹配翻译结果会加上原始的首尾空白符。去除内部环绕换行符的重复空白符后的文本例如将“文本A\n \n文本B”规范为“文本A\n文本B”。同时进行2和3的处理后的文本。相应地当你手动在翻译文件中添加原文译文时XUAT也会自动为这个配对生成多个索引条目以覆盖上述不同情况。这解释了为什么你只需要在翻译文件里写一行「おはよう」「早上好」游戏里无论是「おはよう」还是「おはよう\n」都能被正确翻译。注意这个行为由[Behaviour]下的CacheWhitespaceDifferences配置控制。默认False意味着XUAT会尽量合并只有空白符差异的文本条目使翻译文件更简洁。如果你希望看到所有变体都被记录可以将其设为True但这会让自动生成的文件变得冗长。3. 实战部署从零开始配置你的第一个游戏翻译理论说得再多不如动手一试。我们以一款使用BepInEx作为Mod加载器的Unity游戏为例展示完整的配置流程。BepInEx是目前Unity游戏最流行的Mod框架之一XUAT对其有原生支持。3.1 环境准备与插件安装确认游戏环境首先确保你的游戏已经安装了BepInEx 5.x或6.x版本。通常只需将BepInEx文件解压到游戏根目录运行一次即可。下载XUAT前往GitHub的Release页面下载对应BepInEx的版本通常是XUnity.AutoTranslator-BepInEx-5.x-{VERSION}.zip。安装插件将压缩包内的内容解压。你会看到BepInEx文件夹。将其直接覆盖到游戏的根目录。核心文件会位于游戏根目录\BepInEx\plugins\XUnity.AutoTranslator下。目录结构确认安装完成后XUnity.AutoTranslator目录下应有至少这些文件/文件夹Config.ini- 主配置文件Translation\- 翻译文件目录初始可能为空或只有示例Plugins\- 核心插件DLLTranslators\- 第三方翻译器插件目录可选3.2 核心配置详解Config.ini首次运行游戏后Config.ini会被生成。用记事本或任何文本编辑器打开它我们需要关注几个核心区块[General]区块 - 基础设置Languagezh-CN EndpointGoogleTranslateLanguage目标语言。zh-CN简体中文ja日语en英语等。这是最重要的设置之一。Endpoint在线翻译服务。默认为空禁用。你可以设置为GoogleTranslate谷歌翻译、BaiduTranslate需要配置ID和密钥、DeepLTranslate需要API Key等。初期测试建议用GoogleTranslate。[Behaviour]区块 - 插件行为EnableTranslationTrue EnableUIResizingTrue MaxCharactersPerTranslation400EnableTranslation总开关。EnableUIResizing自动调整UI尺寸。翻译后文本长度可能变化启用此项可尝试自动调整文本框大小以防文字溢出。强烈建议开启。MaxCharactersPerTranslation单次翻译最大字符数。严禁在公开发布的整合包中设置超过400以免对翻译API造成过大压力。[Texture]区块 - 图片翻译高级功能EnableTextureTranslationFalse EnableTextureDumpingFalse TextureDirectoryTranslation\Texture图片翻译功能默认关闭因为它对性能有影响且需要手动制作替换图片。除非你需要汉化UI图片否则保持False。3.3 首次运行与热键操作配置保存后启动游戏。如果安装正确游戏启动时BepInEx控制台如果已启用会显示XUAT的加载日志。ALT0呼出内置配置窗口。你可以在这里实时切换翻译引擎、开关翻译、重新加载翻译文件而无需重启游戏。这是最常用的调试热键。ALTT全局切换翻译的开启/关闭。瞬间在原文和译文间切换方便对比。ALTR重新加载所有翻译文件。当你手动修改了Translation目录下的.txt文件后按此键即可生效无需重启游戏。游戏运行后XUAT开始工作。你会看到游戏内的文本逐渐被替换。首次翻译的文本会稍慢因为要走网络API随后会越来越快。所有被翻译的文本对应关系都会自动记录到Translation\zh-CN\Text\_AutoGeneratedTranslations.txt中。3.4 字体问题解决告别“口口口”翻译中文时游戏原版字体可能不包含中文字形导致显示为方框“口口口”。XUAT提供了字体覆盖功能。获取字体文件你需要一个包含中文的.ttf或.otf字体文件或者为TextMeshPro准备的.asset资源包。社区有打包好的字体资源包如sorrowmoil-MoeFont-for-XUnity.AutoTranslator。配置字体在Config.ini中修改[Behaviour] OverrideFontTextMeshProFonts Materials/LiberationSans SDF对于TextMeshProOverrideFontTextMeshPro可以指定游戏内已存在的TMP字体资源名称如LiberationSans SDF或者指向一个放在游戏根目录的.assets资源包文件不含扩展名。对于UGUI使用OverrideFont并指定系统字体名或资源包路径。放置字体文件如果使用资源包将.assets文件放在游戏根目录与游戏exe同级或BepInEx\plugins\XUnity.AutoTranslator目录下。实操心得不是所有TMP字体资源都兼容。最简单的方法是使用XUAT官方Release页面提供的TMP_Font_AssetBundles.zip中的预编译字体包或者寻找社区为特定游戏制作的字体包。直接使用系统字体名如Microsoft YaHei对TMP可能无效这是Unity的TMP机制限制。4. 高级应用与深度定制当基础翻译满足不了你或者你想制作一个高质量的、可分享的汉化补丁时以下高级功能就派上用场了。4.1 手动翻译与翻译管理自动翻译的质量尤其是对于游戏专有名词、角色台词语气往往不尽如人意。这时就需要手动干预。定位自动生成文件游戏运行一段时间后Translation\zh-CN\Text\_AutoGeneratedTranslations.txt里会积累大量条目。格式是原文译文。创建手动翻译文件不要直接修改_AutoGeneratedTranslations.txt因为每次游戏运行新的自动翻译都可能覆盖你的修改。正确的做法是新建一个.txt文件例如ManualTranslation.txt放在同一个Text目录下。编写翻译在新文件里按照相同格式写入你的修正。例如自动翻译可能将“Potions”译成“药水”但游戏里叫“药剂”你就可以写Potions药剂XUAT会读取Text目录下所有.txt文件并且手动翻译文件的优先级高于自动生成文件。当同一个原文存在多个翻译时以非_开头的文件中的条目为准。使用正则表达式对于有规律的文本正则表达式是神器。比如游戏里所有“Ring 数字”的物品r:^Ring ([0-9])$戒指$1这行规则会将“Ring 1”翻译为“戒指1”。r:表示这是一个标准正则替换。4.2 翻译作用域Scoping精准控制翻译范围有些翻译可能只在特定场景或特定游戏版本下才适用。XUAT支持通过指令来限定翻译的作用域。在翻译文件手动或自动中你可以插入以下指令#set level 5 BossRoom首领房间 #unset level 5 #set exe Game_v1.0.exe OldTitle旧版本标题 #unset exe Game_v1.0.exe#set level [场景ID]此指令后的翻译只在指定的场景ID下生效。场景ID可以通过按CTRLALTNP7热键在游戏中查看。#set exe [执行文件名]此指令后的翻译只在特定的游戏主程序运行时生效。这对于游戏不同版本间的翻译差异非常有用。要启用作用域功能需在Config.ini中设置[Behaviour] EnableTranslationScopingTrue4.3 资源重定向实战修改游戏内文本文件假设一个游戏的所有对话都放在一个叫Dialogue.json的TextAsset里。直接翻译屏幕文本可能效率低下我们可以直接替换这个文件。启用重定向并导出在Config.ini中确保[ResourceRedirector] EnableTextAssetRedirectorTrue EnableDumpingTrue PreferredStoragePathTranslation\{Lang}\RedirectedResources启动游戏进入包含Dialogue.json的场景或触发其加载。XUAT会将该文件导出到Translation\zh-CN\RedirectedResources目录下保持其原始路径结构。修改导出的文件用文本编辑器打开导出的Dialogue.json将其中的英文对话全部翻译并保存。重启游戏再次进入游戏游戏将加载你修改后的Dialogue.json文件所有对话都将直接显示为中文。XUAT的文本翻译功能将不再处理这些已被重定向的文本性能更高且翻译结果100%准确。4.4 开发自己的翻译器插件如果内置的翻译服务都不满足需求比如你想接入某个私有化部署的翻译引擎XUAT允许你通过编写一个简单的DLL来扩展。创建项目新建一个.NET Framework 3.5或.NET Standard类库项目最终目标框架需为.NET 3.5以兼容旧版Unity。引用核心库添加对XUnity.AutoTranslator.Plugin.Core.dll的引用从开发者包中获取。实现接口创建一个类实现ITranslateEndpoint接口或继承自HttpEndpoint等辅助类。你需要提供Id配置中用、FriendlyName显示名并在Initialize方法中读取配置、验证API密钥在Translate或OnCreateRequest/OnExtractTranslation方法中实现与翻译API的通信。处理SSL问题许多Unity游戏使用的旧版Mono默认不信任任何HTTPS证书。你需要在Initialize方法中调用context.DisableCertificateChecksFor(your.api.domain)来禁用对特定域名的证书检查。编译与部署将编译好的DLL放入游戏的BepInEx\plugins\XUnity.AutoTranslator\Translators\目录。然后在Config.ini中将Endpoint设置为你的插件Id。5. 常见问题排查与性能优化指南即使按照指南操作在实际使用中也可能遇到各种问题。这里汇总了高频问题及其解决方案。5.1 翻译不生效或部分生效检查总开关首先确认Config.ini中[General]下的EnableTranslation为True且Endpoint已配置如GoogleTranslate。游戏中按ALT0确认翻译服务已启用。检查热键冲突ALT0,ALTT,ALTR是否被游戏或其他软件占用尝试修改XUAT的热键配置需查代码较复杂或关闭冲突软件。查看日志启用BepInEx的控制台输出并设置[Debug] EnableLogTrue。观察XUAT的日志看是否有错误信息如“Failed to translate”、“Endpoint not available”等。字体问题如果显示为方框是字体缺失。按3.4节配置字体。如果直接不显示空白可能是UI尺寸问题尝试启用EnableUIResizing和ForceUIResizing。特定组件不翻译某些动态生成的UI或特殊插件如对话历史记录窗口可能用了非标准方式渲染文本。可以尝试开启[Behaviour] TextGetterCompatibilityModeTrue。如果知道是其他Mod的UI可以按ALT0暂时关闭翻译看是否恢复以确认问题范围。5.2 游戏崩溃、卡顿或文本错乱关闭纹理翻译如果启用了EnableTextureTranslation首先将其设为False。纹理钩子相对不稳定容易引发崩溃。调整MaxCharactersPerTranslation确保该值未超过400。过长的文本发送给API可能被拒绝或导致处理异常。检查在线服务如果在线翻译服务不稳定或无法访问会导致翻译协程卡住。尝试切换到另一个Endpoint如从GoogleTranslate换到BaiduTranslate或暂时清空Endpoint配置使用纯离线模式。禁用其他Mod与其他Mod特别是其他修改UI或文本的Mod可能存在冲突。尝试仅启用XUAT进行测试。IL2CPP兼容性对于使用IL2CPP后端编译的游戏很多手游和较新的Unity游戏XUAT的文本钩子能力有限。可以尝试使用社区提供的AutoTranslator.IL2CPP.BruteForceFix辅助插件来改善。5.3 性能优化建议善用本地翻译文件将_AutoGeneratedTranslations.txt中翻译质量尚可的条目以及你手动修正的条目整理到独立的手动翻译文件中。游戏启动时会加载所有翻译到内存本地查询速度远快于网络请求。压缩翻译文件Translation目录下的.txt文件可以被压缩成.zip文件XUAT同样能读取。这能略微加快加载速度并减少磁盘占用。禁用不必要的日志在稳定使用后将[Debug] EnableLog设为False。谨慎使用高级功能EnableTextureScanOnSceneLoad、EnableSpriteRendererHooking、EnableTextureDumping等选项都会增加性能开销仅在需要时开启。批处理翻译确保[Behaviour] EnableBatchingTrue默认。这会将多个短文本合并为一个请求发送给翻译API大幅减少请求次数。5.4 制作可分发汉化补丁的注意事项如果你想将配置好XUAT和翻译文件的游戏打包分享给他人请务必遵守清理自动生成文件删除或清空_AutoGeneratedTranslations.txt因为里面可能包含你的个人游戏进度产生的无关文本。只分享你精心维护的手动翻译文件。禁用在线翻译默认配置在分发的Config.ini中不要设置任何需要API密钥的Endpoint如DeepL、Baidu。可以留空或设置为GoogleTranslate因其无需配置。并在说明中告知用户如何自行配置。禁用资源导出功能确保EnableTextureDumping、EnableDumping、DetectDuplicateTextureNames、OutputUntranslatableText等选项均为False。这些功能会产生大量文件或日志不应包含在分发包中。包含字体文件如果你使用了自定义字体请将字体资源包一并打包并提供清晰的安装说明。测试在纯净的游戏环境下测试你的整合包确保安装后能正常启动、翻译生效且无崩溃。XUnity Auto Translator的强大之处在于它构建了一个完整的生态系统对于普通玩家它是开箱即用的实时翻译工具对于汉化组它是高效可定制的翻译管理平台对于开发者它是可深度集成的插件框架。掌握它就等于掌握了为任何Unity游戏开启语言之门的万能钥匙。剩下的就是投入时间去享受游戏或者雕琢一份完美的翻译了。 Unity游戏实时翻译框架XUnity Auto Translator：原理、部署与高级定制指南
1. 项目概述为什么我们需要XUnity Auto Translator如果你是一名Unity游戏玩家尤其是经常接触那些只有日文或英文原版的小众独立游戏、视觉小说或者RPG Maker作品那么语言障碍绝对是你绕不开的一座大山。看着屏幕上密密麻麻的假名或字母再精彩的剧情和系统也变成了天书。传统的汉化补丁虽然好用但往往“一游一补”制作周期长且游戏一旦更新补丁就可能失效。有没有一种方法能让我们实时、自动地将游戏内的文本翻译成母语甚至还能自定义和修正翻译结果呢XUnity Auto Translator后文简称XUAT就是为解决这个问题而生的革命性工具。它不是一个简单的文本替换器而是一个深度集成到Unity游戏运行时的插件式翻译框架。简单来说它能在游戏运行时“截获”所有即将显示在屏幕上的文本调用你配置的翻译服务如谷歌、百度、DeepL等进行实时翻译并将结果“塞回”游戏UI中显示出来。整个过程几乎是实时的你甚至可以在游戏进行中按ALT0呼出配置界面切换翻译引擎或调整设置。更强大的是它支持手动翻译、正则表达式替换、图片资源替换UI贴图、字体覆盖甚至允许开发者为其编写新的翻译器插件。这意味着你不仅可以享受AI翻译的便利还能像维护一个开源项目一样和社区一起打磨出一份精准的、针对特定游戏的翻译库。无论是想无障碍体验生肉游戏还是为爱发电制作汉化补丁XUAT都提供了一个极其强大和灵活的基础设施。2. 核心机制与工作原理解析要玩转XUAT不能只停留在“安装即用”的层面。理解其核心工作机制能帮助你在遇到各种稀奇古怪的问题时快速定位并解决。它的工作流程可以概括为“拦截-查询-替换-渲染”四个步骤。2.1 文本拦截游戏是如何“说话”的Unity游戏显示文本最终无非通过几种常见的UI组件传统的UnityEngine.UI.TextUGUI、更现代的TextMeshProTMP或者老旧的GUILabelIMGUI。XUAT的核心能力之一就是通过Harmony一个.NET函数钩子库或MonoMod在游戏调用这些组件的文本设置方法如Text.text的setter时进行拦截。当游戏执行到类似myTextComponent.text “こんにちは”;这行代码时XUAT的钩子会先一步被触发。它拿到原始的日文字符串“こんにちは”然后开始自己的处理流程。这个过程对游戏本身是透明的游戏依然认为它设置的是原始文本但最终用户看到的却是被替换后的内容。这种在运行时动态修改程序行为的技术是许多游戏Mod得以实现的基础。2.2 翻译查询缓存优先与多级回退拦截到文本后XUAT并不会每次都傻傻地去调用在线翻译API那样速度慢且容易触发频率限制。它遵循一个高效的查询策略内存缓存首先检查这个文本字符串是否已经被翻译过并缓存在内存中。如果是直接使用缓存结果速度最快。本地翻译文件如果内存缓存未命中则查询加载到内存中的翻译字典。这些字典来自你Translation目录下的所有.txt文件包括自动生成的_AutoGeneratedTranslations.txt和手动创建的翻译文件。XUAT会遍历所有文件寻找完全匹配或经过空白符处理的匹配项。在线翻译服务如果本地文件也没有找到翻译XUAT才会将文本发送到你配置的在线翻译端点Endpoint如Google Translate。收到翻译结果后它会同时做两件事一是将结果返回给游戏进行显示二是将这个新的翻译对原文-译文追加写入到_AutoGeneratedTranslations.txt文件中并更新内存缓存。下次再遇到相同文本就会走第1或第2步了。这个策略的精妙之处在于“学习能力”。你玩得越久本地积累的翻译就越多对在线API的依赖就越少翻译速度也就越快最终形成一个离线的、专属于这款游戏的翻译库。2.3 资源重定向不止于文本XUAT的另一个核心模块是Resource Redirector资源重定向器。这解决了更底层的问题游戏中的文本和图片很多是直接存储在Resources文件夹或AssetBundle文件中的。传统的Mod需要解包、修改、再封包过程繁琐且易失效。Resource Redirector允许你在游戏加载这些资源时动态地将其替换为你准备好的版本。例如文本资源TextAsset游戏可能从一个.txt或.json文件里读取剧情对话。启用EnableTextAssetRedirector后XUAT会将这些文件“dump”导出到本地目录如Translation\zh-CN\RedirectedResources。你直接修改这些导出的文件游戏下次运行时就会加载你修改后的版本而不是原始包内的文件。纹理资源Texture游戏UI中的图标、按钮图片可能包含文字。通过启用纹理翻译EnableTextureTranslationXUAT可以导出这些图片让你用PS等工具将其P成中文版再放回指定目录游戏运行时就会显示中文图片。这个机制实现了非侵入式的资源修改你无需动游戏的原始资产包所有修改都在外部目录完成干净且易于管理。2.4 空白符与查找逻辑为什么翻译有时不生效这是新手最容易困惑的地方。游戏里显示的同一句对话在代码层面可能有细微差别比如换行符\n的位置、首尾空格等。XUAT为了最大化匹配成功率采用了智能的空白符处理策略。当它遇到一个待翻译文本时会进行多达四次的查找尝试顺序如下原始文本包含所有空白符。去除首尾空白符后的文本。如果找到匹配翻译结果会加上原始的首尾空白符。去除内部环绕换行符的重复空白符后的文本例如将“文本A\n \n文本B”规范为“文本A\n文本B”。同时进行2和3的处理后的文本。相应地当你手动在翻译文件中添加原文译文时XUAT也会自动为这个配对生成多个索引条目以覆盖上述不同情况。这解释了为什么你只需要在翻译文件里写一行「おはよう」「早上好」游戏里无论是「おはよう」还是「おはよう\n」都能被正确翻译。注意这个行为由[Behaviour]下的CacheWhitespaceDifferences配置控制。默认False意味着XUAT会尽量合并只有空白符差异的文本条目使翻译文件更简洁。如果你希望看到所有变体都被记录可以将其设为True但这会让自动生成的文件变得冗长。3. 实战部署从零开始配置你的第一个游戏翻译理论说得再多不如动手一试。我们以一款使用BepInEx作为Mod加载器的Unity游戏为例展示完整的配置流程。BepInEx是目前Unity游戏最流行的Mod框架之一XUAT对其有原生支持。3.1 环境准备与插件安装确认游戏环境首先确保你的游戏已经安装了BepInEx 5.x或6.x版本。通常只需将BepInEx文件解压到游戏根目录运行一次即可。下载XUAT前往GitHub的Release页面下载对应BepInEx的版本通常是XUnity.AutoTranslator-BepInEx-5.x-{VERSION}.zip。安装插件将压缩包内的内容解压。你会看到BepInEx文件夹。将其直接覆盖到游戏的根目录。核心文件会位于游戏根目录\BepInEx\plugins\XUnity.AutoTranslator下。目录结构确认安装完成后XUnity.AutoTranslator目录下应有至少这些文件/文件夹Config.ini- 主配置文件Translation\- 翻译文件目录初始可能为空或只有示例Plugins\- 核心插件DLLTranslators\- 第三方翻译器插件目录可选3.2 核心配置详解Config.ini首次运行游戏后Config.ini会被生成。用记事本或任何文本编辑器打开它我们需要关注几个核心区块[General]区块 - 基础设置Languagezh-CN EndpointGoogleTranslateLanguage目标语言。zh-CN简体中文ja日语en英语等。这是最重要的设置之一。Endpoint在线翻译服务。默认为空禁用。你可以设置为GoogleTranslate谷歌翻译、BaiduTranslate需要配置ID和密钥、DeepLTranslate需要API Key等。初期测试建议用GoogleTranslate。[Behaviour]区块 - 插件行为EnableTranslationTrue EnableUIResizingTrue MaxCharactersPerTranslation400EnableTranslation总开关。EnableUIResizing自动调整UI尺寸。翻译后文本长度可能变化启用此项可尝试自动调整文本框大小以防文字溢出。强烈建议开启。MaxCharactersPerTranslation单次翻译最大字符数。严禁在公开发布的整合包中设置超过400以免对翻译API造成过大压力。[Texture]区块 - 图片翻译高级功能EnableTextureTranslationFalse EnableTextureDumpingFalse TextureDirectoryTranslation\Texture图片翻译功能默认关闭因为它对性能有影响且需要手动制作替换图片。除非你需要汉化UI图片否则保持False。3.3 首次运行与热键操作配置保存后启动游戏。如果安装正确游戏启动时BepInEx控制台如果已启用会显示XUAT的加载日志。ALT0呼出内置配置窗口。你可以在这里实时切换翻译引擎、开关翻译、重新加载翻译文件而无需重启游戏。这是最常用的调试热键。ALTT全局切换翻译的开启/关闭。瞬间在原文和译文间切换方便对比。ALTR重新加载所有翻译文件。当你手动修改了Translation目录下的.txt文件后按此键即可生效无需重启游戏。游戏运行后XUAT开始工作。你会看到游戏内的文本逐渐被替换。首次翻译的文本会稍慢因为要走网络API随后会越来越快。所有被翻译的文本对应关系都会自动记录到Translation\zh-CN\Text\_AutoGeneratedTranslations.txt中。3.4 字体问题解决告别“口口口”翻译中文时游戏原版字体可能不包含中文字形导致显示为方框“口口口”。XUAT提供了字体覆盖功能。获取字体文件你需要一个包含中文的.ttf或.otf字体文件或者为TextMeshPro准备的.asset资源包。社区有打包好的字体资源包如sorrowmoil-MoeFont-for-XUnity.AutoTranslator。配置字体在Config.ini中修改[Behaviour] OverrideFontTextMeshProFonts Materials/LiberationSans SDF对于TextMeshProOverrideFontTextMeshPro可以指定游戏内已存在的TMP字体资源名称如LiberationSans SDF或者指向一个放在游戏根目录的.assets资源包文件不含扩展名。对于UGUI使用OverrideFont并指定系统字体名或资源包路径。放置字体文件如果使用资源包将.assets文件放在游戏根目录与游戏exe同级或BepInEx\plugins\XUnity.AutoTranslator目录下。实操心得不是所有TMP字体资源都兼容。最简单的方法是使用XUAT官方Release页面提供的TMP_Font_AssetBundles.zip中的预编译字体包或者寻找社区为特定游戏制作的字体包。直接使用系统字体名如Microsoft YaHei对TMP可能无效这是Unity的TMP机制限制。4. 高级应用与深度定制当基础翻译满足不了你或者你想制作一个高质量的、可分享的汉化补丁时以下高级功能就派上用场了。4.1 手动翻译与翻译管理自动翻译的质量尤其是对于游戏专有名词、角色台词语气往往不尽如人意。这时就需要手动干预。定位自动生成文件游戏运行一段时间后Translation\zh-CN\Text\_AutoGeneratedTranslations.txt里会积累大量条目。格式是原文译文。创建手动翻译文件不要直接修改_AutoGeneratedTranslations.txt因为每次游戏运行新的自动翻译都可能覆盖你的修改。正确的做法是新建一个.txt文件例如ManualTranslation.txt放在同一个Text目录下。编写翻译在新文件里按照相同格式写入你的修正。例如自动翻译可能将“Potions”译成“药水”但游戏里叫“药剂”你就可以写Potions药剂XUAT会读取Text目录下所有.txt文件并且手动翻译文件的优先级高于自动生成文件。当同一个原文存在多个翻译时以非_开头的文件中的条目为准。使用正则表达式对于有规律的文本正则表达式是神器。比如游戏里所有“Ring 数字”的物品r:^Ring ([0-9])$戒指$1这行规则会将“Ring 1”翻译为“戒指1”。r:表示这是一个标准正则替换。4.2 翻译作用域Scoping精准控制翻译范围有些翻译可能只在特定场景或特定游戏版本下才适用。XUAT支持通过指令来限定翻译的作用域。在翻译文件手动或自动中你可以插入以下指令#set level 5 BossRoom首领房间 #unset level 5 #set exe Game_v1.0.exe OldTitle旧版本标题 #unset exe Game_v1.0.exe#set level [场景ID]此指令后的翻译只在指定的场景ID下生效。场景ID可以通过按CTRLALTNP7热键在游戏中查看。#set exe [执行文件名]此指令后的翻译只在特定的游戏主程序运行时生效。这对于游戏不同版本间的翻译差异非常有用。要启用作用域功能需在Config.ini中设置[Behaviour] EnableTranslationScopingTrue4.3 资源重定向实战修改游戏内文本文件假设一个游戏的所有对话都放在一个叫Dialogue.json的TextAsset里。直接翻译屏幕文本可能效率低下我们可以直接替换这个文件。启用重定向并导出在Config.ini中确保[ResourceRedirector] EnableTextAssetRedirectorTrue EnableDumpingTrue PreferredStoragePathTranslation\{Lang}\RedirectedResources启动游戏进入包含Dialogue.json的场景或触发其加载。XUAT会将该文件导出到Translation\zh-CN\RedirectedResources目录下保持其原始路径结构。修改导出的文件用文本编辑器打开导出的Dialogue.json将其中的英文对话全部翻译并保存。重启游戏再次进入游戏游戏将加载你修改后的Dialogue.json文件所有对话都将直接显示为中文。XUAT的文本翻译功能将不再处理这些已被重定向的文本性能更高且翻译结果100%准确。4.4 开发自己的翻译器插件如果内置的翻译服务都不满足需求比如你想接入某个私有化部署的翻译引擎XUAT允许你通过编写一个简单的DLL来扩展。创建项目新建一个.NET Framework 3.5或.NET Standard类库项目最终目标框架需为.NET 3.5以兼容旧版Unity。引用核心库添加对XUnity.AutoTranslator.Plugin.Core.dll的引用从开发者包中获取。实现接口创建一个类实现ITranslateEndpoint接口或继承自HttpEndpoint等辅助类。你需要提供Id配置中用、FriendlyName显示名并在Initialize方法中读取配置、验证API密钥在Translate或OnCreateRequest/OnExtractTranslation方法中实现与翻译API的通信。处理SSL问题许多Unity游戏使用的旧版Mono默认不信任任何HTTPS证书。你需要在Initialize方法中调用context.DisableCertificateChecksFor(your.api.domain)来禁用对特定域名的证书检查。编译与部署将编译好的DLL放入游戏的BepInEx\plugins\XUnity.AutoTranslator\Translators\目录。然后在Config.ini中将Endpoint设置为你的插件Id。5. 常见问题排查与性能优化指南即使按照指南操作在实际使用中也可能遇到各种问题。这里汇总了高频问题及其解决方案。5.1 翻译不生效或部分生效检查总开关首先确认Config.ini中[General]下的EnableTranslation为True且Endpoint已配置如GoogleTranslate。游戏中按ALT0确认翻译服务已启用。检查热键冲突ALT0,ALTT,ALTR是否被游戏或其他软件占用尝试修改XUAT的热键配置需查代码较复杂或关闭冲突软件。查看日志启用BepInEx的控制台输出并设置[Debug] EnableLogTrue。观察XUAT的日志看是否有错误信息如“Failed to translate”、“Endpoint not available”等。字体问题如果显示为方框是字体缺失。按3.4节配置字体。如果直接不显示空白可能是UI尺寸问题尝试启用EnableUIResizing和ForceUIResizing。特定组件不翻译某些动态生成的UI或特殊插件如对话历史记录窗口可能用了非标准方式渲染文本。可以尝试开启[Behaviour] TextGetterCompatibilityModeTrue。如果知道是其他Mod的UI可以按ALT0暂时关闭翻译看是否恢复以确认问题范围。5.2 游戏崩溃、卡顿或文本错乱关闭纹理翻译如果启用了EnableTextureTranslation首先将其设为False。纹理钩子相对不稳定容易引发崩溃。调整MaxCharactersPerTranslation确保该值未超过400。过长的文本发送给API可能被拒绝或导致处理异常。检查在线服务如果在线翻译服务不稳定或无法访问会导致翻译协程卡住。尝试切换到另一个Endpoint如从GoogleTranslate换到BaiduTranslate或暂时清空Endpoint配置使用纯离线模式。禁用其他Mod与其他Mod特别是其他修改UI或文本的Mod可能存在冲突。尝试仅启用XUAT进行测试。IL2CPP兼容性对于使用IL2CPP后端编译的游戏很多手游和较新的Unity游戏XUAT的文本钩子能力有限。可以尝试使用社区提供的AutoTranslator.IL2CPP.BruteForceFix辅助插件来改善。5.3 性能优化建议善用本地翻译文件将_AutoGeneratedTranslations.txt中翻译质量尚可的条目以及你手动修正的条目整理到独立的手动翻译文件中。游戏启动时会加载所有翻译到内存本地查询速度远快于网络请求。压缩翻译文件Translation目录下的.txt文件可以被压缩成.zip文件XUAT同样能读取。这能略微加快加载速度并减少磁盘占用。禁用不必要的日志在稳定使用后将[Debug] EnableLog设为False。谨慎使用高级功能EnableTextureScanOnSceneLoad、EnableSpriteRendererHooking、EnableTextureDumping等选项都会增加性能开销仅在需要时开启。批处理翻译确保[Behaviour] EnableBatchingTrue默认。这会将多个短文本合并为一个请求发送给翻译API大幅减少请求次数。5.4 制作可分发汉化补丁的注意事项如果你想将配置好XUAT和翻译文件的游戏打包分享给他人请务必遵守清理自动生成文件删除或清空_AutoGeneratedTranslations.txt因为里面可能包含你的个人游戏进度产生的无关文本。只分享你精心维护的手动翻译文件。禁用在线翻译默认配置在分发的Config.ini中不要设置任何需要API密钥的Endpoint如DeepL、Baidu。可以留空或设置为GoogleTranslate因其无需配置。并在说明中告知用户如何自行配置。禁用资源导出功能确保EnableTextureDumping、EnableDumping、DetectDuplicateTextureNames、OutputUntranslatableText等选项均为False。这些功能会产生大量文件或日志不应包含在分发包中。包含字体文件如果你使用了自定义字体请将字体资源包一并打包并提供清晰的安装说明。测试在纯净的游戏环境下测试你的整合包确保安装后能正常启动、翻译生效且无崩溃。XUnity Auto Translator的强大之处在于它构建了一个完整的生态系统对于普通玩家它是开箱即用的实时翻译工具对于汉化组它是高效可定制的翻译管理平台对于开发者它是可深度集成的插件框架。掌握它就等于掌握了为任何Unity游戏开启语言之门的万能钥匙。剩下的就是投入时间去享受游戏或者雕琢一份完美的翻译了。