使用Unity Localization插件进行项目本地化实战详解
在使用Unity开发游戏的过程中，本地化是必不可少的。网络上也有很多的本地化工具，本次我介绍的是Unity官方提供的Localization插件，大家可以在Package Manager进行安装
一、语言配置，本地化表创建
在Project Setting中找到Localization，（需要先创建这个Localization Setting文件）点击Locale Generator选择需要本地化的语言。创建好后会得到这些文件，这些文件可以用于切换语言（后面做切换语言界面时会用），先把英语拖入作为默认语言。
打开本地化表工具，创建本地化表
创建UILocalization和ScriptLocalization两个本地化表，分别用作UI和代码本地化。会得到以下文件
可以在表格中添加一些需要本地化的文本（这里只是先试试，先不要添加太多，后面会用Excel进行管理），注意最左侧的Key值，这个key值后续用来确定文本
二、使用Localize String Event进行本地化
给UI上的文本挂载LocalizeStringEvent脚本，点击其中最上面的String Reference搜索之前表格中创建的本地化文本。搜索Key值或者本地化的文本都可以搜得到。
注：如果显示不完整，可以调节右下角的小球
然后将LocalizeStringEvent的Update String调整为Text.text，就是要刷新的脚本。任何的string都可以刷新，Text Mesh Pro也是可以的
运行游戏查看效果，可以临时先使用右上角的下拉框调节本地化语言，界面上的文本会实时刷新。
三、UI本地化
我先将本地化的需求暂时分成两类
1，UI本地化：UI界面上面固定不变的文本
2，Script本地化：代码中实时更改的文本，包括（String.Format+数值），动态弹出的提示语，NPC对话，物品名字等
为了后续教程，我们暂时约定在制作界面时，UI本地化的内容正常命名，Script本地化的对象以$开头命名，例如：
首先，需要知道有哪些文本需要本地化，并给它们自动挂载上LocalizeStringEvent脚本。可以在Editor目录下创建一个扩展脚本实现此功能。
using System.Collections.Generic; using System.IO; using UnityEditor; using UnityEngine; using UnityEngine.Events; using UnityEngine.Localization; using UnityEngine.Localization.Components; using UnityEngine.UI; public class LocalizeTextEditor : EditorWindow { private string outputFilePath = "LocalizedText.txt"; // 指定的txt文件路径 private List<string> localizedTextEntries = new List<string>(); [MenuItem("Custom/Localize Text")] private static void ShowWindow() { GetWindow<LocalizeTextEditor>("Localize Text"); } private void OnGUI() { GUILayout.Label("Localize Text Editor", EditorStyles.boldLabel); if (GUILayout.Button("Localize Selected GameObjects")) { LocalizeSelectedGameObjects(); } if (GUILayout.Button("Save Localized Text to File")) { SaveLocalizedTextToFile(); } if (GUILayout.Button("Print Script Localize Selected GameObjects")) { PrintScriptLocalize(); } } private void LocalizeSelectedGameObjects() { localizedTextEntries.Clear(); GameObject[] selectedObjects = Selection.gameObjects; foreach (GameObject selectedObject in selectedObjects) { Text[] textComponents = selectedObject.GetComponentsInChildren<Text>(true); foreach (Text textComponent in textComponents) { if (!textComponent.name.StartsWith("$")) { // 需要本地化的Text if(textComponent.gameObject.GetComponent<LocalizeStringEvent>() == null) { LocalizeStringEvent localizeEvent = textComponent.gameObject.AddComponent<LocalizeStringEvent>(); // 标记对象为“已修改” EditorUtility.SetDirty(selectedObject); } // 添加到列表 string entry = $"{selectedObject.name}\t{textComponent.name}\t{textComponent.text}"; localizedTextEntries.Add(entry); } } } } private void SaveLocalizedTextToFile() { if(!File.Exists(outputFilePath)) { File.Create(outputFilePath).Dispose(); } using (StreamWriter writer = new StreamWriter(outputFilePath, true)) { foreach (string entry in localizedTextEntries) { writer.WriteLine(entry); } } Debug.Log($"Localized text entries saved to {outputFilePath}"); } private void PrintScriptLocalize() { GameObject[] selectedObjects = Selection.gameObjects; foreach (GameObject selectedObject in selectedObjects) { Text[] textComponents = selectedObject.GetComponentsInChildren<Text>(true); foreach (Text textComponent in textComponents) { if (textComponent.name.StartsWith("$")) { Debug.Log($"{selectedObject.name}\t{textComponent.name}\t{textComponent.text}"); } } } } }
我本来还想自动给LocalizeStringEvent的Update String赋值，但是未能实现。如果哪位高人有办法可以在评论区指出
全选需要本地化的UI预制体，依次点击扩展窗口的第1和第2个按钮，可以给非$开头的Text（你们如果命名规则不一样，请自行修改脚本）自动挂载LocalizeStringEvent脚本
这些Text中的内容会输出到txt中，可以查看（注：txt默认应该在项目根路径）
四、使用Excel表格管理本地化文本
右键点击本地化表的选项卡，选择导出CSV
如果使用Office，导出时选择UTF-8即可。如果和我一样使用WPS，请另存为xlsx格式，不然部分语言会乱码。
2024.2更新：不建议另存为xlsx格式，因为ID超过15位会舍入。导致原本设置好的组件找不到本地化ID
可以使用python的pandas库将数据全部变成string，再写入xlsx
import pandas as pd df = pd.read_csv('UILocalization.csv') df = df.astype(str) df.to_excel('UILocalization.xlsx', index=False, sheet_name="UILocalization") df2 = pd.read_csv('ScriptLocalization.csv') df2 = df.astype(str) df2.to_excel('ScriptLocalization.xlsx', index=False, sheet_name="ScriptLocalization")
将之前txt中的内容复制到表格中，由于我输出的是\t，内容会自动分布到表格的不同列，大家可以把根据预制体名字来给Key起名。
丢给AI或者翻译软件翻译之后，对于没有空格的语言，可以使用alt+回车在适当位置输入换行，例如：中文，日语等。Unity的自适应换行只会在有空格的地方换行
对于WPS用户，我们需要将xlsx转回CSV才能在Unity中读取，这里使用python的pandas库进行处理。
import pandas as pd # 读取 Excel 文件 df = pd.read_excel("UILocalization.xlsx", sheet_name="UILocalization") # 将 DataFrame 写入 CSV 文件 df.to_csv('dataUI.csv', encoding='utf-8', index=False) df2 = pd.read_excel("ScriptLocalization.xlsx", sheet_name="ScriptLocalization") df2.to_csv('dataScript.csv', encoding='utf-8', index=False)
这里还处理了后面的Script本地化文件，大家还没看完后续教程的，可以先注释后两行代码
在本地化表导出CSV的上面还有导入CSV，这里就不截图了，导入之后就可以得到我们刚才在Office或WPS中编辑的表格
五、Script本地化
还是全选所有UI预制体，这次点击第三个按钮，会在控制台中输出所有$开头的Text。这些Text都是在代码中更改内容的，只能对其查找所有引用，然后逐个更改。
那么，如何在代码中获取本地化的内容呢，我们需要创建一个单例的LocalizationManager，提供一个获取本地化内容的函数。
以防止有编程小白，这里介绍一下单例模式，单例模式就是类最多只有一个对象，并且有一个指向该对象的静态指针。在Unity中可以用以下代码实现一个简单的单例模式
using UnityEngine; public class Singleton<T> : MonoBehaviour where T : Singleton<T> { protected static T _instance; public static T Ins { get { return _instance; } } protected virtual void Awake() { _instance = (T)this; } protected virtual void OnDestroy() { if (_instance == this) { _instance = null; } } }
在场景中创建一个（DontDestroyOnLoad）不会销毁的对象，并挂载LocalizationManager脚本
using System.Collections; using System.Collections.Generic; using UnityEngine; using UnityEngine.Localization; using UnityEngine.Localization.Settings; using UnityEngine.Localization.Tables; using UnityEngine.ResourceManagement.AsyncOperations; namespace UI { public class LocalizationManager : Singleton<LocalizationManager> { private StringTable ScriptStringTable; //代码本地化表 void Start() { if (LocalizationSettings.AvailableLocales.Locales.Count > 0) { GetLocalizationTable(); } else { LocalizationSettings.InitializationOperation.Completed += OnLocalizationInitialized; } LocalizationSettings.SelectedLocaleChanged += OnLocaleChanged; } protected override void OnDestroy() { base.OnDestroy(); LocalizationSettings.SelectedLocaleChanged -= OnLocaleChanged; } /// <summary> /// 本地化初始化完成 /// </summary> private void OnLocalizationInitialized(AsyncOperationHandle<LocalizationSettings> handle) { if (handle.Status == AsyncOperationStatus.Succeeded) { Debug.Log("Localization initialized successfully!"); GetLocalizationTable(); } else { Debug.LogError("Localization initialization failed."); } } /// <summary> /// 切换语言 /// </summary> private void OnLocaleChanged(Locale newLocale) { GetLocalizationTable(); } /// <summary> /// 获取本地化表 /// </summary> public void GetLocalizationTable() { ScriptStringTable = LocalizationSettings.StringDatabase.GetTable("ScriptLocalization"); //Debug.LogWarning(ScriptStringTable.GetEntry("CommonTip_NoItem").GetLocalizedString()); } /// <summary> /// 获取本地化文本 /// </summary> public string GetLocalizedString(string key) { return ScriptStringTable.GetEntry(key).GetLocalizedString(); } } }
这里我们注册了两个事件，一个是LocalizationSettings.InitializationOperation.Completed，这个是LocalizationSettings初始化完成时调用。由于本地化插件是异步初始化，代码运行到start时不一定初始化完成，此处通过判断可用语言是否大于0来判断有没有初始化完成。
另一个事件是LocalizationSettings.SelectedLocaleChanged，这个是LocalizationSettings切换语言是调用。这两个事件都会执行获取本地化表的操作。对于之前在代码中更改的Text，可用调用GetLocalizedString来获取本地化文本。
例如：
物品名字要进行本地化，key值是GameItem_ID，每个物品ID不同
和之前使用表格管理UILocalization表类似，我们也使用表格管理ScriptLocalization表。
六、语言切换界面
创建一个这样的UI界面，我设计的是每个按钮都能点。当前使用的语言是绿的。
给每个按钮拖上一个Locale，就是之前最开始创建的用于切换语言的
/// <summary> /// 刷新按钮状态 /// </summary> public void RefreshItemChooseState() { Locale currentLocale = LocalizationSettings.SelectedLocale; foreach (var item in languageItems) { item.SetChooseState(currentLocale == item.locale); } } /// <summary> /// 设置语言 /// </summary> public void SetLanguage(Locale locale) { if(locale == LocalizationSettings.SelectedLocale) { return; } LocalizationSettings.Instance.SetSelectedLocale(locale); Client.Ins.Player.PlayerLanguage = locale.LocaleName; RefreshItemChooseState(); }
获取当前语言：LocalizationSettings.SelectedLocale，获取之后和每个按钮上面拖入的Locale比对，一样的就是当前语言
设置语言：LocalizationSettings.Instance.SetSelectedLocale(locale);把拖入的Locale设置进去，就可以切换语言。
以下为拓展内容：
设置完语言之后，最好能够保存下来，用户下次启动自动使用。这里把locale.LocaleName，也就是语言的名字保存下来。
大家可以用任意方式保存一个string，我这边用的json，这里就涉及到游戏存档设计了，超出了本文的讨论范围。大家可以自行设计游戏存档，反正能够存取当前语言名字（public string PlayerLanguage）就行了
这里仍然使用了之前提到的LocalizationSettings.InitializationOperation.Completed事件，在LocalizationSettings初始化完成之后设置为保存的语言。
/// <summary> /// 本地化初始化完成 /// </summary> private void OnLocalizationInitialized(AsyncOperationHandle<LocalizationSettings> handle) { if (handle.Status == AsyncOperationStatus.Succeeded) { Debug.Log("Localization initialized successfully!"); UseSaveLanguage(); } else { Debug.LogError("Localization initialization failed."); } } /// <summary> /// 使用保存的语言 /// </summary> private void UseSaveLanguage() { var locales = LocalizationSettings.AvailableLocales.Locales; foreach (var locale in locales) { if (locale.LocaleName == PlayerLanguage) { LocalizationSettings.Instance.SetSelectedLocale(locale); break; } } }
