1. 项目概述XUnity.AutoTranslator 是什么以及它能为你做什么如果你是一名Unity游戏的爱好者尤其是经常接触那些尚未推出官方中文版本的作品那么你一定对游戏内大段的日文、英文文本感到头疼。手动截图、切图、丢进翻译软件再对照着修改游戏文件这套流程不仅繁琐而且破坏了沉浸式体验。XUnity.AutoTranslator以下简称XUA就是为了解决这个痛点而生的神器。它是一个高级的、可高度定制的翻译插件能够自动拦截并翻译Unity引擎游戏中显示的文本实现近乎实时的“内嵌汉化”效果。简单来说XUA就像是一个潜伏在游戏进程内的同声传译。当游戏试图在屏幕上显示一段文字时XUA会先“听到”这段原文然后立刻在自己的“词库”包括在线翻译服务和本地翻译文件里查找对应的译文最后将译文替换上去显示给玩家。整个过程对游戏本身是透明的你无需修改任何游戏原始文件也无需等待漫长的汉化组发布补丁。无论是视觉小说VN中的大段对话还是角色扮演游戏RPG里的物品描述和技能说明甚至是其他Mod的界面文字它都有能力处理。这个项目的核心价值在于其“自动化”和“可扩展性”。自动化意味着开箱即用配置好翻译服务如谷歌翻译后首次遇到的文本会被自动翻译并缓存下次再见时直接显示速度极快。可扩展性则体现在它不仅仅是一个翻译器更是一个强大的游戏文本修改框架。你可以手动润色自动生成的生硬翻译可以编写正则表达式Regex处理复杂的文本组合可以替换游戏内的图片资源如UI图标甚至可以为其开发新的翻译服务接口。对于Mod作者它还提供了丰富的API允许其他插件与之交互或避免冲突。因此无论你是一名只想轻松玩上外语游戏的普通玩家还是一个希望为社区贡献高质量翻译的汉化者亦或是一名想要深度定制游戏体验的开发者XUnity.AutoTranslator都提供了一个从入门到精通的、功能强大的平台。接下来我将带你从零开始彻底掌握这个工具。2. 核心架构与工作原理解析要高效使用XUA不能只停留在“怎么安装”的层面理解其核心架构和工作原理能让你在遇到问题时快速定位并充分发挥其潜力。XUA并非一个简单的“文本替换器”而是一个由多个模块协同工作的复杂系统。2.1 核心模块分工XUA主要由两大核心模块构成AutoTranslator自动翻译器和ResourceRedirector资源重定向器。它们的关系类似于“前台”和“后台”。AutoTranslator前台-文本处理核心这是用户直接交互的部分。它负责文本钩取Hooking利用Harmony或MonoMod等技术在游戏运行时拦截所有对UI文本组件如UnityEngine.UI.Text, TextMeshPro的赋值操作。这是实现实时翻译的基础。翻译查询Translation Lookup当拦截到一段文本后插件会按照预设的优先级进行查询。优先级从高到低通常是手动翻译文件.txt - 内存中的缓存翻译 - 在线翻译服务。文本处理流水线查询到的译文并非直接显示。它会经过一个处理流水线包括预处理如移除多余空格、翻译、后处理如罗马字音标处理以及UI适配如字体替换、文本框自动缩放。配置与管理提供热键如ALTT开关翻译、ALTR重载翻译、配置界面和丰富的配置文件Config.ini来管理所有行为。ResourceRedirector后台-资源劫持引擎这是一个独立且更底层的库为AutoTranslator提供强大的扩展能力。它允许插件在游戏加载资源如文本资产TextAsset、纹理Texture的瞬间将其重定向到外部自定义文件。这意味着文本资源替换游戏原本从resources.assets包内读取的脚本文件可以被重定向到Translation/目录下的同名文件实现更彻底、更稳定的文本修改。纹理替换游戏内的图片、UI图标可以被替换这对于完整汉化比如替换带有文字的按钮图片至关重要。通用性ResourceRedirector本身不依赖AutoTranslator任何其他Mod也可以利用它来修改游戏资源这使得XUA生态非常强大。2.2 翻译流程与缓存机制一次完整的翻译请求其内部流程如下触发游戏代码调用textComponent.text “おはよう”。拦截XUA的钩子函数捕获到这个调用和文本内容“おはよう”。标准化插件对原始文本进行标准化处理例如去除首尾空白字符处理内部的换行符和连续空格生成一个用于查询的“键Key”。这是为了应对游戏在不同场景下可能对同一段文本进行微小格式调整的情况。四级查询插件会尝试用四个不同严格程度的“键”去查询翻译键1原始文本。键2去除首尾空白的文本。键3去除内部换行符周围空白的文本。键4同时去除首尾空白和内部换行空白的文本。 只要任一查询命中即返回对应的翻译并保留原始文本的空白格式。这个设计非常巧妙确保了翻译的鲁棒性。命中缓存如果在本地翻译文件或内存缓存中找到译文则直接进入步骤7。调用在线服务如果未命中缓存且配置了在线翻译端点如GoogleTranslate插件会将文本发送给该服务。收到回复后译文会被同时写入屏幕和自动生成翻译文件_AutoGeneratedTranslations.txt中以备下次使用。后处理与渲染对译文进行可能的后处理如罗马字转换然后根据配置决定是否替换字体、调整UI组件大小最后将处理后的文本设置回游戏的UI组件。缓存机制是XUA流畅体验的关键。首次运行游戏时由于所有文本都需要在线翻译可能会有明显的卡顿和网络请求。但随着游戏进行_AutoGeneratedTranslations.txt文件会不断增长下次启动游戏时绝大部分文本都直接从本地文件读取速度极快。这也是为什么社区汉化组可以分享这个文件——它本质上就是一个积累了高质量翻译的词典。2.3 配置文件Config.ini的核心作用BepInEx/config/AutoTranslatorConfig.ini是XUA的大脑。几乎所有功能都通过它来开关和微调。理解几个关键区块至关重要[General]设置源语言、目标语言、翻译端点等全局选项。[Behaviour]控制插件核心行为如是否启用UI重设大小、字体覆盖、批处理翻译等。[Texture]控制纹理图片替换功能的开关和行为。[Http]网络相关设置如用户代理。各个翻译服务如[Google],[Baidu]的专属配置区块用于填写API密钥。实操心得不要被长长的默认配置文件吓到。对于新手90%的选项保持默认即可。你只需要关注[General]里的Language目标语言如zh-CN和Endpoint翻译服务如GoogleTranslate。其他高级选项等你有特定需求如字体显示不正常、文本框显示不全时再按图索骥去修改。3. 从零开始安装、配置与基础使用理论说得再多不如动手实践。我们以最流行的Mod管理器BepInEx为例讲解完整的安装和配置流程。3.1 环境准备与插件安装安装BepInEx首先确保你的目标Unity游戏已经安装了正确版本的BepInEx。通常将BepInEx压缩包内的文件解压到游戏根目录即可。运行一次游戏生成BepInEx文件夹结构。下载XUnity.AutoTranslator前往GitHub的Release页面下载对应你Mod管理器的版本。对于BepInEx 5.x选择XUnity.AutoTranslator-BepInEx-5.x-{VERSION}.zip。安装插件将下载的ZIP文件解压你会看到BepInEx文件夹。将其直接拖拽到游戏根目录与现有的BepInEx文件夹合并。关键路径是BepInEx/plugins/XUnity.AutoTranslator。安装ResourceRedirector通常上述插件包内已包含必需的XUnity.ResourceRedirector.dll。确保它存在于BepInEx/plugins或BepInEx/patchers目录下根据版本不同。这是纹理替换和高级资源重定向功能的基础。3.2 首次运行与基础配置启动游戏运行游戏如果安装成功游戏启动时在日志中应该能看到XUnity.AutoTranslator的加载信息通常BepInEx会在游戏窗口标题栏或控制台显示。生成配置文件首次运行后关闭游戏。在BepInEx/config目录下会生成AutoTranslatorConfig.ini。编辑核心配置用记事本或任何文本编辑器打开AutoTranslatorConfig.ini。找到并修改以下关键参数[General] ; 设置目标语言为简体中文 Languagezh-CN ; 设置在线翻译服务为谷歌翻译免费版 EndpointGoogleTranslate ; 翻译输出目录通常保持默认即可 DirectoryTranslation\{Lang}\Text ; 自动生成翻译的文件名 OutputFile_AutoGeneratedTranslations.txt配置在线翻译服务以GoogleTranslate为例默认的谷歌翻译端点使用的是公开的网页接口可能不稳定或被限制。如果遇到翻译失败可以尝试以下两种方案之一方案A使用备用公共接口。在配置文件中找到[Google]区块尝试修改ServiceUrl注意此操作需自行寻找可用且合规的公共服务接口并确保其符合相关法律法规和使用条款。方案B推荐更稳定使用其他翻译服务。将Endpoint改为BaiduTranslate或YandexTranslate等并在对应的配置区块如[Baidu]填入你从相应平台申请的合法API密钥AppId和AppSecret。这是最可靠的方式。3.3 基础使用与热键配置完成后再次启动游戏。你会发现游戏内的文本正在被逐步翻译。以下是几个必须掌握的基础热键ALT0打开翻译端点选择菜单。如果你配置了多个翻译服务可以在这里实时切换。ALTT全局翻译开关。这是最重要的热键可以一键开启或关闭所有文本翻译。当翻译导致游戏UI错乱或你想看原文时就用它。ALTR重新加载翻译文件。当你手动修改了Translation\zh-CN\Text\目录下的任何.txt翻译文件后按此热键无需重启游戏即可生效。ALT反引号键打开插件的控制台如果启用可以查看详细日志。注意事项首次运行游戏翻译速度取决于你的网络和翻译服务的响应速度。建议在游戏主菜单或非关键剧情处等待一段时间让插件完成一批初始文本的翻译和缓存。后续游戏体验会非常流畅。4. 进阶实战手动翻译、正则表达式与资源替换当自动翻译无法满足你对质量的要求或者遇到一些特殊文本格式时就需要手动介入。这是XUA从“能用”到“好用”的关键。4.1 创建与维护手动翻译文件自动生成的_AutoGeneratedTranslations.txt文件是翻译的起点但直接编辑它并非最佳实践因为游戏更新或插件重装可能会覆盖它。正确的方法是创建独立的手动翻译文件。定位目录打开BepInEx\plugins\XUnity.AutoTranslator\Translation\zh-CN\Text\假设目标语言是简体中文。创建新文件新建一个文本文件例如MyManualTranslations.txt。文件名可以任意只要扩展名是.txt。编写翻译文件内容遵循“原文译文”的格式一行一条。例如おはようございます早上好 アイテム物品 これはテストです这是一个测试优先级规则XUA会读取Text目录下所有的.txt文件。手动翻译文件的优先级高于自动生成的文件。如果同一原文出现在多个文件后加载的文件会覆盖先加载的通常按文件名排序。你可以利用这一点来修正自动翻译的错误。使用正则表达式对于有规律的文本可以使用正则表达式进行批量匹配。在翻译行前加上r:标识。例如游戏中有很多“リング 数字”格式的物品名r:^シンプルリング ([0-9])$简易戒指 $1这条规则会将“シンプルリング 1”翻译为“简易戒指 1”。$1代表正则表达式中第一个括号捕获的内容。4.2 处理复杂文本拆分器正则表达式Splitter Regex这是XUA的一个杀手级功能。有些游戏会将多个文本片段在代码中拼接后再显示例如“[ATK10] 炎の剑”。如果我们只为“炎の剑”提供了翻译那么面对这个拼接后的字符串插件将无法匹配。此时可以使用拆分器正则表达式以sr:开头先拆解再分别翻译各部分最后重组。sr:^\[(?stat[\w\s])(?num_i[\\-]{1}[0-9])?\](?after[\s\S])?$[${stat}${num_i}]${after}让我们拆解这个复杂的例子sr:声明这是一个拆分器正则表达式。^\[...\]...$匹配以[开头后面跟着]再跟着其他内容的字符串。(?stat[\w\s])命名捕获组stat匹配属性名如ATK, DEF包含字母、数字、下划线和空格。(?num_i[\\-]{1}[0-9])?命名捕获组num_i匹配或-后跟数字如10。?表示这个组是可选的。_i后缀是关键它告诉插件这个组的内容不需要翻译原样传递。(?after[\s\S])?命名捕获组after匹配]之后的所有内容即“炎の剑”。[\s\S]匹配任何字符包括换行。[${stat}${num_i}]${after}重组格式。${stat}和${after}会被送去翻译如果词库里有${num_i}则直接原样插入。这样插件遇到“[ATK10] 炎の剑”时会将其拆分为stat“ATK”num_i“10”after“炎の剑”。然后查找“炎の剑”的翻译比如“Flame Sword”最后组合成“[ATK10] Flame Sword”显示出来。实操心得编写正则表达式时务必先在小型文本上测试。可以将游戏中的原文日志通过开启EnableLogTrue查看复制出来在正则表达式测试工具中验证。过度复杂或低效的正则表达式会影响游戏性能。4.3 纹理图片替换实战对于UI中包含文字的图片如菜单按钮、图标纯文本翻译无能为力。这时就需要纹理替换功能。启用功能在Config.ini中找到[Texture]区块进行如下设置[Texture] EnableTextureTranslationTrue EnableTextureDumpingTrue ; 首次使用时开启用于导出游戏内图片 TextureDirectoryTranslation\Texture TextureHashGenerationStrategyFromImageName ; 大多数情况用这个性能最好导出纹理启动游戏并进入包含目标图片的场景。XUA会将检测到的纹理图片自动导出到Translation\Texture目录下。文件名会包含哈希值如button_ok [ABCD1234-EF567890].png。编辑图片用图像处理软件如Photoshop, GIMP打开导出的图片将其中的外文修改为中文。重要保存时务必保留原文件名和哈希值部分。你可以修改哈希值之前的部分例如将button_ok [ABCD1234-EF567890].png重命名为确认按钮 [ABCD1234-EF567890].png但[ABCD1234-EF567890]必须原封不动。关闭导出享受成果编辑完成后将配置中的EnableTextureDumpingFalse以防止后续游戏继续导出已处理的图片。重启游戏修改后的图片就应该显示出来了。注意事项纹理替换功能对性能有一定影响尤其是开启EnableTextureScanOnSceneLoad时。建议只替换必要的UI图片对于大量的3D模型贴图通常没有替换必要且会显著增加内存占用。在发布整合包时绝对不要开启EnableTextureDumping、EnableTextureToggling等调试选项。5. 高级定制与故障排除指南当你熟悉基础操作后可能会遇到一些特殊需求或棘手问题。本章节将深入高级配置和常见故障的解决方案。5.1 字体显示问题与解决方案翻译为中文、韩文等非拉丁语系文字时游戏原版字体可能缺少对应字形导致显示为方框□□□。解决方案1字体覆盖OverrideFont在[Behaviour]部分设置OverrideFont针对UGUI或OverrideFontTextMeshPro针对TextMeshPro。这会将游戏中所有文本的字体强制替换为你指定的字体。对于UGUI你需要提供一个.ttf或.otf字体文件放在游戏根目录然后在配置中指定文件名如OverrideFontmyfont.ttf。更可靠的方式是制作一个包含该字体资源的AssetBundle但这需要Unity Editor知识。对于TextMeshPro你可以指定一个系统字体名如Microsoft YaHei或者使用插件作者提供的预编译字体AssetBundle在Release页面的TMP_Font_AssetBundles压缩包中解压后放入游戏根目录并配置路径。解决方案2后备字体FallbackFontTextMeshPro这是更优雅的解决方案仅当主字体缺失字符时才使用后备字体。配置FallbackFontTextMeshPro指向一个支持目标语言的TMP字体资源如Fonts Materials/LiberationSans SDF Fallback。这需要游戏内置或通过AssetBundle提供了相应的后备字体资源。实操心得优先尝试FallbackFontTextMeshPro。如果游戏使用的是TextMeshPro且资源包中包含多语言字体资源此方法能完美解决缺字问题且不影响原有字体风格。如果不行再使用全局覆盖OverrideFontTextMeshPro。5.2 UI布局错乱与自动重设大小翻译后的文本长度通常与原文不同可能导致文本框装不下文字被截断或重叠。启用自动重设大小在[Behaviour]中确保EnableUIResizingTrue。XUA会尝试自动调整文本框的HorizontalOverflow和VerticalOverflow属性并可能微调字体大小和行间距通过ResizeUILineSpacingScale。手动精细控制如果自动调整效果不佳可以使用resizer.txt文件进行手动控制。首先在配置中开启EnableTextPathLoggingTrue然后游戏中操作需要调整的UI查看日志输出中该UI的完整路径。接着在Translation\zh-CN\Text\目录下创建resizer.txt添加如下规则UI/Canvas/Panel/TextChangeFontSizeByPercentage(0.9);AutoResize(true, 12, 36)这条规则将匹配路径包含UI/Canvas/Panel/Text的所有文本组件将其字体大小缩放至90%并启用自动重设大小限制最小字体12最大字体36。5.3 常见问题与排查技巧实录即使配置正确在实际使用中也可能遇到各种问题。下面是一个快速排查清单问题现象可能原因解决方案游戏启动崩溃或黑屏1. BepInEx或XUA版本与游戏不兼容。2. 与其他Mod冲突。1. 检查游戏社区确认使用的BepInEx和XUA版本是否正确。2. 暂时移除其他Mod仅保留XUA测试。使用BepInEx的Doorstop日志和LogOutput.log定位错误。翻译完全不生效1. 配置文件Language或Endpoint设置错误。2. 插件未正确加载。1. 检查AutoTranslatorConfig.ini确保Language和Endpoint有效。2. 查看游戏启动日志确认XUnity.AutoTranslator已加载。按ALT0看是否有菜单弹出。部分文本未被翻译1. 文本来自IMGUI其他Mod的界面。2. 文本被游戏特殊处理如动态拼接。3. 文本长度超过MaxCharactersPerTranslation默认1000。1. 尝试在配置中设置EnableIMGUITrue注意性能。2. 使用拆分器正则表达式sr:处理。3. 适当调大MaxCharactersPerTranslation但注意不要超过400出于对翻译服务的尊重。翻译后游戏逻辑出错游戏通过检查显示的文本来决定分支逻辑常见于一些ADV游戏。在[Behaviour]中设置TextGetterCompatibilityModeTrue。这会让插件“欺骗”游戏使其认为显示的仍是原文。在线翻译失败错误429等使用的公共翻译接口达到请求限制或被屏蔽。1. 更换Endpoint如使用BaiduTranslate或YandexTranslate并配置API密钥。2. 增加[Http]下的MaxConcurrentRequests最大并发请求数和RequestInterval请求间隔来降低请求频率。内存占用过高或游戏变卡1. 启用了纹理替换且CacheTexturesInMemoryTrue。2. 正则表达式过于复杂或低效。3. 启用了EnableTextureScanOnSceneLoad。1. 关闭不必要的纹理替换或设置CacheTexturesInMemoryFalse。2. 审查并优化翻译文件中的正则表达式。3. 仅在需要导出纹理时开启此选项完成后关闭。自动生成的翻译文件混乱插件输出了大量无意义或重复的文本。检查配置中OutputUntranslatableText和CacheWhitespaceDifferences是否为False。确保MaxCharactersPerTranslation设置合理。定期清理_AutoGeneratedTranslations.txt中的垃圾条目。日志是你的最佳朋友遇到任何疑难杂症第一件事是开启详细日志。在Config.ini中设置[Debug]部分的EnableConsoleTrue和EnableLogTrue。然后重启游戏操作复现问题最后仔细查看控制台输出的日志信息里面通常包含了插件每一步的操作和可能的错误原因。掌握XUnity.AutoTranslator的过程是一个从“自动翻译使用者”到“游戏本地化工程师”的转变。它提供的不仅是一个工具更是一套方法论。从基础的配置使用到手动翻译维护再到利用正则表达式和资源重定向解决复杂问题每一步都让你对游戏本地化的理解更深一层。这个工具的强大之处在于其社区生态无数玩家和汉化者贡献的翻译文件、正则规则和字体资源让许多小众游戏也能享受到高质量的本地化体验。希望这篇指南能成为你探索这个世界的坚实起点。