1. 项目概述与核心价值最近在做一个面向海外发行的独立游戏项目团队规模不大但目标市场覆盖了英语、日语、韩语和简体中文。立项之初我们就定下了一个铁律绝对不能把文本硬编码在代码里。这几乎是所有有出海打算的团队都会踩的第一个坑。想象一下策划每次改一句台词程序员就要去翻代码、提交、打包、测试效率低不说还极易出错。更麻烦的是后期如果要增加新的语言支持比如西班牙语或法语难道要程序员去代码里一个个找字符串替换吗这显然是不可持续的。因此我们需要一套成熟、高效且易于维护的文本本地化方案。经过一番调研和对比我们最终敲定了Luban QFramework这套组合拳。Luban负责解决配置数据的结构化管理和多语言Excel表的生成与加载而QFramework则提供了一个轻量、优雅的UI框架和资源管理方案两者结合能让我们用极低的成本实现一套工程化、可扩展的多语言系统。这个方案的核心价值在于“解耦”与“流程化”。它将文本内容从代码逻辑中彻底剥离交给策划和翻译人员在Excel中维护同时通过Luban强大的代码生成能力将Excel配置表转化为强类型的C#数据类在Unity中可以直接以面向对象的方式安全访问。QFramework的架构则让UI文本的本地化切换变得像调用一个事件那么简单。对于中小团队而言这套方案不需要依赖昂贵的第三方本地化插件完全自主可控且能无缝融入现有的开发流程。接下来我就把这套从零搭建的完整流程包括那些踩过的坑和总结出的最佳实践毫无保留地分享出来。2. 技术选型深度解析为什么是LubanQFramework在Unity生态中实现本地化的方案不少有Unity官方的Localization Package需Unity 2020.3也有像I2 Localization、Lean Localization这样成熟的第三方资产。我们最终选择自研方案基于Luban和QFramework是经过多方面权衡的。2.1 Luban不仅仅是配置表工具Luban的核心定位是一个强大的配置数据解决方案。它最初源自游戏行业用于解决游戏内大量数值、道具、关卡等配置数据的管理问题。它的工作流非常清晰你定义好数据结构通过xml、json或自定义格式然后在Excel中填充数据最后通过Luban命令行工具一键生成对应语言如C#、Java、Lua等的代码文件和二进制/Json数据文件。对于多语言支持Luban有原生且优雅的设计。你可以在同一个Excel工作簿中为每种语言创建单独的表Sheet或者更常见的使用多列模式即一列ID多列对应不同语言的文本。Luban在生成代码时会根据你的配置为每个文本字段生成对应语言的属性。在运行时只需根据当前语言标识动态切换读取的列即可。选择Luban的理由强类型安全生成的C#类是强类型的避免了字符串Key拼写错误导致的运行时异常。你可以像访问普通类属性一样访问配置cfg.Item[1001].NameCN或cfg.Item[1001].GetName(“en”)IDE的智能提示和编译期检查让开发体验极佳。极高的性能Luban支持将Excel数据序列化为紧凑的二进制格式如bytes。在Unity中加载二进制文件的速度远快于解析Json或Excel这对移动端游戏尤其重要。与策划工作流完美契合策划和翻译人员最熟悉的就是Excel。他们可以在一个文件里维护所有语言版本利用Excel的公式、筛选、批注等功能极大提升内容生产效率。版本管理如Git对Excel文件的支持也相对友好。扩展性强除了文本Luban可以管理游戏中几乎所有静态配置。将多语言文本作为配置的一部分统一管理减少了系统复杂度。2.2 QFramework提供架构支撑的轻量框架QFramework是一个设计精巧的Unity开发框架它提供了基于C#的简单易用的架构模式如Command命令、Model模型、**System系统**等并内置了资源管理、UI管理、音频管理等常用模块。在本地化系统中我们主要利用QFramework的以下特性事件系统TypeEventSystem这是实现语言实时切换的关键。当用户切换语言时我们只需要抛出一个LanguageChangedEvent事件所有注册了该事件的UI文本控件会自动响应并更新显示内容。这种基于事件的解耦方式比遍历查找所有Text组件要高效和优雅得多。UI组件与数据绑定QFramework的UIPanel和UIComponent体系可以方便地管理UI生命周期。我们可以创建一个LocalizationText组件继承自Text或TextMeshProUGUI让它自动监听语言切换事件并更新文本。这避免了手动为每个Text组件写脚本的繁琐。优雅的代码组织QFramework鼓励将业务逻辑分解为独立的Command和System这使得本地化相关的代码如加载配置、切换语言逻辑可以很好地被封装和管理不与核心游戏逻辑混杂。两者的分工与结合Luban扮演“数据提供者”角色。它负责定义“有什么文本”数据Schema以及提供“文本的具体内容”多语言数据。QFramework扮演“架构与驱动者”角色。它提供事件机制来驱动UI更新并提供组件化方案来方便地消费Luban提供的数据。这套组合的优势在于它们各自专注于自己最擅长的领域通过清晰的接口Luban生成的C#类进行通信共同构建了一个松耦合、高内聚的解决方案。对于已经使用或打算使用QFramework架构的项目集成起来会非常顺畅即使没有使用QFramework你也可以借鉴其事件驱动的思想用普通的C#事件或消息中心来实现同样的效果。3. 完整实战流程从Excel到屏幕显示下面我将以创建一个简单的“物品名称”多语言显示为例带你走通整个流程。3.1 第一步环境准备与Luban配置首先你需要在项目中集成Luban。推荐使用其发布的Unity版本插件或者通过Git Submodule引入Luban的源码。这里假设你已有一个干净的Unity项目以2021.3 LTS为例。创建配置目录结构在项目根目录Assets同级或Assets内创建一个GameConfig文件夹用于存放所有配置相关文件。建议结构如下GameConfig/ ├── Datas/ # 存放原始的Excel配置表 ├── Gen/ # 存放Luban生成的C#代码和数据文件 ├── Defines/ # 存放Luban的数据定义文件.xml 或 .xlsx └── LubanTools/ # 存放Luban命令行工具和生成脚本定义数据Schema在Defines文件夹下创建一个__tables__.xlsx文件这是Luban的约定用于定义所有表。或者更推荐使用xml格式进行定义因为它更清晰。我们创建一个localization.xml!-- GameConfig/Defines/localization.xml -- module nameLocalization table nameTbText valueText inputDatas/Localization.xlsx/ /module同时创建一个根定义文件__root__.xml!-- GameConfig/Defines/__root__.xml -- root module nameLocalization includelocalization.xml/ /root这里定义了一个名为TbText的表其数据来源于Datas/Localization.xlsx文件对应的数据行类型名为Text。准备Luban工具与生成脚本从Luban的GitHub Release页面下载对应你操作系统的命令行工具如luban.exefor Windows放入LubanTools文件夹。然后编写一个简单的生成脚本如gen.batfor Windowsecho off REM GameConfig/LubanTools/gen.bat set WORK_DIR%~dp0.. luban.exe ^ --conf %WORK_DIR%/Defines/__root__.xml ^ --input_data_dir %WORK_DIR%/Datas ^ --output_code_dir %WORK_DIR%/Gen/Code ^ --output_data_dir %WORK_DIR%/Gen/DataBytes ^ --gen_types code_cs_bin,data_bin ^ --naming_convention:module bean:Cs Pascal ^ --naming_convention:bean_member Cs Pascal ^ -s unity pause这个脚本告诉Luban根据定义文件读取Datas目录下的Excel将生成的C#代码放到Gen/Code将生成的二进制数据文件放到Gen/DataBytes并指定了命名规范和目标平台为Unity。3.2 第二步设计并填充多语言Excel表现在在Datas文件夹下创建Localization.xlsx。这是策划和翻译人员工作的主战场。一个推荐的表结构设计如下Key (string)Desc (string)CN (string)EN (string)JP (string)KO (string)ITEM_SWORD_NAME剑的名称青铜剑Bronze Swordブロンズソード브론즈 소드ITEM_SWORD_DESC剑的描述一把普通的青铜剑。A common bronze sword.普通のブロンズソード。평범한 브론즈 검입니다.UI_MAIN_TITLE主界面标题冒险者公会Adventurer Guild冒険者ギルド모험가 길드列设计解析Key唯一标识符建议使用大写英文和下划线如UI_MAIN_BUTTON_START。这是代码中引用的依据。Desc对该条目的中文描述仅供开发、策划人员查阅帮助理解Key的用途不会出现在游戏中。CN/EN/JP/KO对应语言的文本列。列名就是语言代码清晰明了。你可以根据需要添加FR法语、ES西班牙语等列。注意Luban默认将第一行作为列名字段名第二行开始才是数据。确保你的Excel没有多余的标题行。另外对于包含换行、引号等特殊字符的文本在Excel中正常输入即可Luban在生成时会正确处理转义。3.3 第三步运行Luban生成代码与数据双击运行之前写好的gen.bat脚本。如果一切配置正确你会在Gen文件夹下看到生成的成果Gen/Code/里面会有一个Cfg命名空间包含TbText类和Text类。TbText是一个单例提供了根据Key获取Text行数据的方法。Text类则包含了Key、Desc以及各个语言属性如CN,EN。Gen/DataBytes/里面会有TbText.bytes这样的二进制数据文件。将这些生成的C#代码文件复制到Unity项目的Assets/Scripts/GameConfig目录下确保在Unity编译范围内。将.bytes数据文件复制到Assets/StreamingAssets/Config或某个Resources文件夹下以便运行时加载。3.4 第四步在QFramework架构下实现本地化管理器现在我们需要在Unity中创建一个核心的管理器来加载Luban的数据并提供语言切换功能。创建本地化数据模型在QFramework中我们通常使用Model来管理数据。// LocalizationModel.cs using QFramework; using Cfg; // 引入Luban生成的配置命名空间 public class LocalizationModel : AbstractModel { // 当前语言属性变更时触发事件 private SystemLanguage m_CurrentLanguage SystemLanguage.English; public SystemLanguage CurrentLanguage { get m_CurrentLanguage; set { if (m_CurrentLanguage ! value) { m_CurrentLanguage value; // 使用QFramework的事件系统发送语言变更事件 TypeEventSystem.Global.SendLanguageChangedEvent(); } } } // Luban配置表数据 public Tables ConfigTables { get; private set; } public override void OnInit() { // 在初始化时加载配置数据 LoadConfig(); } private void LoadConfig() { // 从StreamingAssets或Resources加载bytes数据 TextAsset textAsset Resources.LoadTextAsset(Config/TbText); if (textAsset ! null) { var bytes textAsset.bytes; ConfigTables new Tables(Loader); // 假设我们只加载了TbText如果有多个表需要更复杂的加载器 } else { Log.E(Failed to load localization config!); } } // 辅助方法根据Key和当前语言获取文本 public string GetText(string key) { if (ConfigTables null) return $[{key}]; var textData ConfigTables.TbText.GetOrDefault(key); if (textData null) return $[{key}]; switch (CurrentLanguage) { case SystemLanguage.ChineseSimplified: return textData.CN; case SystemLanguage.English: return textData.EN; case SystemLanguage.Japanese: return textData.JP; case SystemLanguage.Korean: return textData.KO; default: return textData.EN; // 默认回退到英文 } } // Bytes加载器供Luban的Tables构造函数使用 private static ByteBuf Loader(string file) { // 简化示例实际应根据file参数加载不同的bytes // 这里我们假设只加载了一个表 TextAsset asset Resources.LoadTextAsset($Config/{file}); return new ByteBuf(asset.bytes); } } // 语言变更事件 public struct LanguageChangedEvent {}创建本地化文本组件这是一个用于替换Unity原生Text/TextMeshProUGUI的组件它会自动响应语言切换。// LocalizationText.cs using UnityEngine; using UnityEngine.UI; using QFramework; using TMPro; // 如果使用TextMeshPro public class LocalizationText : MonoBehaviour { [SerializeField] private string m_TextKey; // 在Inspector中配置的Key如UI_MAIN_TITLE private Text m_Text; private TMP_Text m_TMPText; private void Awake() { m_Text GetComponentText(); m_TMPText GetComponentTMP_Text(); UpdateText(); } private void OnEnable() { // 注册语言变更事件 TypeEventSystem.Global.RegisterLanguageChangedEvent(OnLanguageChanged).UnRegisterWhenGameObjectDestroyed(gameObject); } private void OnLanguageChanged(LanguageChangedEvent e) { UpdateText(); } private void UpdateText() { var model this.GetModelLocalizationModel(); string localizedStr model.GetText(m_TextKey); if (m_Text ! null) m_Text.text localizedStr; if (m_TMPText ! null) m_TMPText.text localizedStr; } // 编辑器下方便预览的方法 #if UNITY_EDITOR private void OnValidate() { if (Application.isPlaying) { UpdateText(); } } #endif }创建语言切换命令在QFramework中使用Command来执行改变状态的逻辑。// ChangeLanguageCommand.cs using QFramework; public class ChangeLanguageCommand : AbstractCommand { private readonly SystemLanguage m_TargetLanguage; public ChangeLanguageCommand(SystemLanguage lang) { m_TargetLanguage lang; } protected override void OnExecute() { var model this.GetModelLocalizationModel(); model.CurrentLanguage m_TargetLanguage; // 这里可以添加存档逻辑将语言选择保存到PlayerPrefs或存档文件 PlayerPrefs.SetString(GameLanguage, m_TargetLanguage.ToString()); PlayerPrefs.Save(); } }3.5 第五步在游戏中使用初始化在游戏启动时如一个启动场景的控制器中初始化QFramework的架构并加载LocalizationModel。void Start() { // 初始化QFramework框架 QFramework.QApp.Init(); // 获取或注册Model var model this.GetModelLocalizationModel(); // 可以从存档加载上次选择的语言 string savedLang PlayerPrefs.GetString(GameLanguage, SystemLanguage.English.ToString()); if (System.Enum.TryParse(savedLang, out SystemLanguage lang)) { model.CurrentLanguage lang; } }配置UI在需要本地化的UIText或TextMeshProUGUI组件上移除原有的Text脚本添加LocalizationText组件并在Text Key字段填入Excel中对应的Key如UI_MAIN_TITLE。切换语言在语言设置按钮的点击事件中执行切换命令。// 例如在一个下拉菜单的OnValueChanged事件中 public void OnLanguageDropdownChanged(int index) { SystemLanguage lang (SystemLanguage)index; // 假设下拉选项顺序与枚举对应 new ChangeLanguageCommand(lang).Execute(); }当命令执行后LocalizationModel的CurrentLanguage改变触发LanguageChangedEvent事件。所有激活的LocalizationText组件都会收到事件并自动调用UpdateText()方法从模型中获取最新语言的文本并刷新显示。4. 进阶优化与避坑指南一套基础系统搭建完成后要考虑实际项目中的复杂情况和性能优化。4.1 动态字体加载与Fallback处理不同语言可能需要不同的字体文件。例如中文需要包含大量汉字的字体而韩文、日文也需要对应的字体支持。如果全部打包进游戏体积会很大。解决方案按需加载将字体文件作为AssetBundle或Addressable资源进行管理。在LocalizationModel中根据当前语言动态加载对应的字体Asset。设置默认字体在LocalizationText组件中可以添加一个Font Asset或Font字段的数组与支持的语言一一对应。在UpdateText()中不仅更新文本也更新字体。Font Fallback对于TextMeshPro可以利用其强大的Fallback字体功能。准备一个基础字体如英文然后为中文、日文、韩文分别配置Fallback字体链。这样当基础字体缺少某个字符时会自动从Fallback字体中查找。4.2 文本参数替换与格式化游戏中的文本常常需要动态插入变量如“玩家{0}获得了{1}件物品”。Luban的Excel单元格里可以直接写“玩家{0}获得了{1}件物品”。在代码中处理public string GetTextFormat(string key, params object[] args) { string format GetText(key); // 先获取本地化后的格式字符串 try { return string.Format(format, args); } catch (FormatException) { Log.E($Format error for key: {key}, format: {format}); return format; } }在LocalizationText组件中可以扩展支持格式化参数或者更常见的做法是在需要动态文本的地方如UI逻辑代码中直接调用GetTextFormat方法。注意不同语言的语序可能完全不同参数位置可能需要调整。Luban本身不处理这个需要翻译人员在对应语言列中正确放置{0}、{1}等占位符。这是一个重要的协作规范。4.3 非UI文本的本地化除了UI游戏中的脚本化对象ScriptableObject、配置表里的描述字段、音频字幕等也需要本地化。ScriptableObject可以在其中定义一个LocalizationKey字段然后在OnEnable或通过一个统一的初始化阶段利用LocalizationModel获取当前语言文本进行替换。配置表其他字段如果其他配置表如道具表、任务表也有文本字段强烈建议将这些字段也引用到主本地化表。即在道具表中Name字段不直接存文本而是存一个Key如ITEM_SWORD_NAME。这样能保证所有文本出口统一方便管理和翻译。音频字幕可以创建一个字幕表包含音频Clip的引用和对应的文本Key。播放音频时同步从本地化系统获取当前语言的字幕显示。4.4 常见问题与排查技巧生成的代码编译错误检查Luban生成脚本中的命名空间和命名规范参数是否与你的项目设置冲突。确保生成的C#文件放在了正确的Assembly Definition或脚本文件夹中。运行时找不到Key在GetText方法中如果找不到Key我们返回了$[{key}]作为占位符方便在游戏中快速定位未配置的文本。在开发阶段可以将其改为Log.Error以便及时发现问题。文本未更新检查LocalizationText组件是否被正确添加到GameObject上并且Text Key字段填写无误。检查LocalizationModel是否被正确初始化和注册到QFramework的架构中。在切换语言后确认LanguageChangedEvent事件被成功触发。可以在事件监听方法里加Debug.Log验证。Excel修改后未生效确保修改Excel后重新运行了Luban生成脚本。确保生成的.bytes数据文件被更新并复制到了Unity项目的正确目录如StreamingAssets。重要Unity不会自动检测StreamingAssets文件夹外部的变化。如果你将数据文件放在StreamingAssets内并且通过Application.streamingAssetsPath读取在编辑器模式下修改文件后需要重启Unity或手动刷新因为Unity会缓存文件信息。一种更可靠的做法是在开发期使用Resources.Load或AssetDatabase.LoadAssetAtPath并确保数据文件在Assets目录内这样Unity的Asset Database能跟踪变化。多语言Excel维护冲突当多人同时编辑一个Excel文件时容易产生Git冲突。建议的协作流程是“主翻译人员维护主Excel文件其他人员通过分支或提交请求Pull Request来提交修改”。也可以考虑将不同语言的列拆分成不同的文件由不同的翻译人员维护最后在生成环节通过脚本合并但这会增加Luban配置的复杂度。5. 性能考量与扩展方向对于大型项目当本地化文本条目达到上万条时需要关注性能。数据加载优化Luban生成的二进制格式.bytes本身加载很快。关键在于避免在切换语言时重复解析数据。我们的方案中LocalizationModel在初始化时就将所有数据加载到内存中的Tables对象里。切换语言时只是切换一个CurrentLanguage枚举值然后触发UI更新这个过程是O(1)的性能开销极低。内存优化所有文本字符串都会常驻内存。如果文本量巨大比如大型RPG的海量任务对话可以考虑按需加载。例如将文本按模块如“第一章”、“UI通用”、“系统提示”拆分到不同的Excel表和.bytes文件中在进入相应模块时才加载对应的配置表。扩展方向运行时语言热重载在编辑器模式下可以监听本地化数据文件的变化当检测到文件被修改并重新导入后自动触发LocalizationModel重新加载数据和刷新所有UI。这能极大提升翻译和校对阶段的工作效率。与翻译平台对接一些专业的翻译管理平台如Crowdin、Localize支持导出为Excel或CSV格式。可以编写脚本将平台导出的文件格式转换为Luban所需的Excel格式从而实现本地化流程的自动化。图片、音频等资源的本地化思路与文本类似。可以为图片资源定义Key如SPLASH_LOGO_CN,SPLASH_LOGO_EN。在LocalizationModel中根据当前语言Key映射到不同的Sprite或AudioClip资源地址然后通过QFramework的ResKit或Unity的Addressables系统进行加载。这套基于Luban和QFramework的本地化方案在我们项目中已经稳定运行了多个版本。它最大的优点就是清晰和可控。所有文本有唯一的源头Excel所有逻辑有明确的路径事件驱动无论是程序员、策划还是翻译都能在各自熟悉的环节高效工作。对于预算有限、追求工程效率的中小团队来说这无疑是一个值得投入学习和实践的解决方案。