跳到主要内容

Localization

重要 注意 提醒

Coding Style wiki​

Localization 是 LocalizationSystem 的本地化核心 (成员皆为 static)，由项目通过回调提供支持语系与语言表解析 (onAddSupportedLanguages、onParsingLanguageData、onChangeLanguage)，并提供语系切换 (ChangeLanguage)、系统语系检测与代码取字 (GetStringByCode) API；完整初始流程可参考模块介绍。

命名空间OxGKit.LocalizationSystem
类型public class Localization (成员皆为 static)
源码Localization.cs
using OxGKit.LocalizationSystem;

快速上手​

using System.Collections.Generic;
using OxGKit.LocalizationSystem;

// 1. 声明支持语系
Localization.onAddSupportedLanguages = (supportedLanguages) =>
{
    supportedLanguages.Add(LangType.English);
    supportedLanguages.Add(LangType.ChineseTraditional);
};

// 2. 提供语言表解析 (数据来源由项目自行决定: JSON、表格导出、服务器...)
Localization.onParsingLanguageData = (langType, langData) =>
{
    foreach (var pair in langSheet[langType.ToString()])
        langData.TryAdd(pair.Key, pair.Value);
    return true; // 解析成功返回 true
};

// 3. 语系切换成功后刷新 UI 文字
Localization.onChangeLanguage = (langType) => RefreshAllLocalizedTexts();

// 4. 首次切换 (例如使用系统语系，不支持时自动回退 English)
Localization.ChangeLanguage(Localization.systemLanguage);

// 5. UI 一律通过代码取字
string title = Localization.GetStringByCode("ui.title");

通用规则​

必须实现的回调​

  1. 赋值 onAddSupportedLanguages 声明支持语系。
  2. 赋值 onParsingLanguageData 提供语言表解析 (解表所需的数据来源需先准备完成)。
  3. (建议) 订阅 onChangeLanguage 刷新 UI 文字。

重要 onParsingLanguageData 未赋值或解析返回 false 时，ChangeLanguage 会直接抛出异常。

缓存机制​

注意 GetSupportedLanguages 与转译表 API 首次调用后即缓存结果 (不会再次触发回调)，因此必须先赋值 onAddSupportedLanguages，再调用任何支持语系相关 API (含 systemLanguage、IsSupportedLanguage 等)。

语系保存​

提醒 模块不负责保存所选语系，由项目自行保存/还原 LangType，还原时建议先以 GetAndCheckIsSupportedLanguage 校正。

回调成员​

成员总览​

成员说明
onAddSupportedLanguages新增支持语系回调。
onParsingLanguageData解析语言表数据回调 (ChangeLanguage 时调用解析)。
onChangeLanguage切换语系回调 (切换成功后通知)。

onAddSupportedLanguages​

public static Action<HashSet<LangType>> onAddSupportedLanguages

新增支持语系回调；于 GetSupportedLanguages 首次被调用时触发，将项目支持的语系加入 supportedLanguages 集合。

Localization.onAddSupportedLanguages = (supportedLanguages) =>
{
    supportedLanguages.Add(LangType.English);
    supportedLanguages.Add(LangType.ChineseTraditional);
    supportedLanguages.Add(LangType.ChineseSimplified);
    supportedLanguages.Add(LangType.Japanese);
    supportedLanguages.Add(LangType.Korean);
};

onParsingLanguageData​

public static Func<LangType, Dictionary<string, string>, bool> onParsingLanguageData

解析语言表数据回调；ChangeLanguage 时调用解析，需将指定语系的 Code -> Text 键值填入 langData (切换成功后该字典会被缓存为当前语言表)，解析成功返回 true。

Localization.onParsingLanguageData = (langType, langData) =>
{
    // Your lang sheet (can load from json or server)
    if (langSheet.ContainsKey(langType.ToString()))
    {
        // The ref langData will be cached by Localization
        foreach (var pair in langSheet[langType.ToString()])
            langData.TryAdd(pair.Key, pair.Value);
        return true;
    }
    return false;
};

重要 未赋值或返回 false 时，ChangeLanguage 会抛出异常；解表所需的数据来源 (游戏数据库、下载的语言表等) 需在初始本地化前准备完成。

onChangeLanguage​

public static Action<LangType> onChangeLanguage

切换语系成功后的通知回调，参数为切换后的语系；适合在此刷新 UI 显示文字 (搭配 GetStringByCode)。

private void _InitEvents()
{
    // Refresh lang text callback
    Localization.onChangeLanguage += this._RefreshLanguage;
}

private void _RefreshLanguage(LangType langType)
{
    this.titleText.text = Localization.GetStringByCode("ui.title");
}

提醒 每次切换成功都会触发，回调内容需可重复执行 (建议仅做文字/数据重绘，勿在其中进行一次性注册)。

属性​

成员总览​

成员说明
currentLanguage当前语系 (只读)。
systemLanguage系统语系 (经支持语系检测，不支持回退 English)。

currentLanguage​

public static LangType currentLanguage { get; private set; }

当前语系 (只读)；初始值取自 systemLanguage，仅在 ChangeLanguage 切换成功后更新。

// 保存所选语系 (模块不负责保存)
PlayerPrefs.SetInt("language", (int)Localization.currentLanguage);

systemLanguage​

public static LangType systemLanguage { get; }

获取系统语系：将 OS 系统语言通过 GetSystemLanguageToLangType 对应为 LangType，再经 GetAndCheckIsSupportedLanguage 检测，不属于支持语系则一律回退 LangType.English。

// 首次进入游戏无保存语系时，以系统语系作为默认
Localization.ChangeLanguage(Localization.systemLanguage);

语系切换与取字​

方法总览​

方法说明
ChangeLanguage切换语系与验证语系合法性。
GetStringByCode根据代码获取语言表中的对应文字。

ChangeLanguage​

public static void ChangeLanguage(LangType langType)

切换语系与验证语系合法性，流程如下：

  1. 调用 onParsingLanguageData 解析指定语系的语言表。
  2. 验证 langType 是否属于支持语系：
    • 是：缓存语言表数据、更新 currentLanguage，并触发 onChangeLanguage。
    • 否：输出警告 (The language type is not supported) 并维持当前语系 (不更新、不触发回调)。
Localization.ChangeLanguage(LangType.Japanese);

// 保存所选语系 (模块不负责保存)
PlayerPrefs.SetInt("language", (int)Localization.currentLanguage);

重要 onParsingLanguageData 未赋值或解析失败 (返回 false) 会抛出 Exception。

注意 传入前可先以 GetAndCheckIsSupportedLanguage 校正 (避免保存的旧语系值已不受支持)。

GetStringByCode​

public static string GetStringByCode(string code)

根据代码 (Code) 获取当前语言表中的对应文字；查无代码时返回 "Unknown Text"。

this.titleText.text = Localization.GetStringByCode("ui.title");

注意 尚未成功执行过 ChangeLanguage (无语言表数据) 时会抛出 Exception；QA 验证时可将 "Unknown Text" 视为缺漏字符串代码的信号。

支持语系查询​

方法总览​

方法说明
GetSupportedLanguages获取当前支持语系集合。
IsSupportedLanguage是否属于支持语系。
GetAndCheckIsSupportedLanguage检测语系，不支持一律返回 English。
GetSystemLanguageToLangType获取系统语言对应的 LangType 定义。
GetSupportedLanguagesMappingByLangType获取语系文字对照表 (Key = LangType)。
GetSupportedLanguagesMappingByLangDesc获取语系文字对照表 (Key = LangDesc)。

GetSupportedLanguages​

public static HashSet<LangType> GetSupportedLanguages()

获取当前支持语系集合；首次调用时触发 onAddSupportedLanguages 收集并缓存，之后直接返回缓存结果。

IsSupportedLanguage​

public static bool IsSupportedLanguage(LangType langType)

是否属于支持语系。

GetAndCheckIsSupportedLanguage​

public static LangType GetAndCheckIsSupportedLanguage(LangType langType)

获取与检测是否属于支持语系类型：支持则原值返回；不支持一律返回 LangType.English。适合用于校正保存值/系统值。

var savedLang = (LangType)PlayerPrefs.GetInt("language", (int)Localization.systemLanguage);
Localization.ChangeLanguage(Localization.GetAndCheckIsSupportedLanguage(savedLang));

GetSystemLanguageToLangType​

public static LangType GetSystemLanguageToLangType()

获取 OS 系统语言 (UnityEngine.Application.systemLanguage) 对应的 LangType 定义 (不经支持语系检测)；无法对应时返回 LangType.Unspecified。

提醒 部分语言 Unity SystemLanguage 未内置 (详见 LangType 对照表的系统检测栏)，系统检测无法返回，但仍可作为自定义支持语系使用；Hindi 需 Unity 2022.3 / Unity 6000.0 以上才支持检测。

GetSupportedLanguagesMappingByLangType​

public static Dictionary<LangType, string> GetSupportedLanguagesMappingByLangType()

获取支持语系的语系文字对照表，Key = LangType (ex: LangType.Spanish -> "Español")；适合用于生成语言菜单的显示文字 (首次调用后缓存)。

GetSupportedLanguagesMappingByLangDesc​

public static Dictionary<string, LangType> GetSupportedLanguagesMappingByLangDesc()

获取支持语系的语系文字对照表，Key = LangDesc (ex: "Español" -> LangType.Spanish)；适合用于语言菜单由选项文字反查语系进行切换 (首次调用后缓存)。

// 语言菜单: 以对照文字显示选项，选择后反查 LangType 进行切换
var mapping = Localization.GetSupportedLanguagesMappingByLangDesc();
Localization.ChangeLanguage(mapping["简体中文"]);

LangType​

世界语言定义 (byte 枚举)，共 72 个值 (Unspecified + 71 种世界语言)。

类型public enum LangType : byte
源码Languages.cs

表格符号说明：

枚举值语言对照文字系统检测
Unspecified未指定─✓ (无法对应时的回退值)
Arabic阿拉伯语العربية✓
ChineseSimplified中文简体简体中文✓
ChineseTraditional中文繁体繁體中文✓
Dutch荷兰语Nederlands✓
English英语English✓
French法语Français✓
German德文Deutsch✓
Italian意大利语Italiano✓
Portuguese葡萄牙语Protuguês✓
Spanish西班牙语Español✓
Bengali孟加拉语বাংলা✗
Croatian克罗地亚语hrvatski✗
Czech捷克语čeština✓
Danish丹麦语Dansk✓
Greek希腊文ελληνικά✓
Hebrew希伯来文עברית✓
Hindi印度语हिंदी✓ (Unity 2022.3+)
Hungarian匈牙利语Magyar✓
Indonesian印尼语Bahasa Indonesia✓
Japanese日语日本語✓
Korean韩语한국의✓
Malay马来语Bahasa Melayu✗
Perisan波斯语فارسی✗
Polish波兰语Polski✓
Romanian罗马尼亚语româna✓
Russian俄语Русский✓
Serbian塞尔维亚语српски✓
Swedish瑞典语Svenska✓
Thai泰语ไทย✓
Turkish土耳其语Türkçe✓
Urdu乌尔都语اردو✗
Vietnamese越南语tiếng việt✓
Catalan加泰罗尼亚语 (西班牙)catalá✓
Latvian拉脱维亚语Latviski✓
Lithuanian立陶宛语Lietuvių✓
Norwegian挪威语Norsk bokmal✓
Slovak斯洛伐克语Slovenčina✓
Slovenian斯洛文尼亚语Slovenščina✓
Bulgarian保加利亚语български✓
Ukrainian乌克兰语українська✓
Filipino菲律宾语Tagalog✗
Finnish芬兰语Suomi✓
Afrikaans南非荷兰语Afrikaans✓
Romansh罗曼什语 (瑞士)Rumantsch✗
Burmese缅甸语 (官方)ဗမာ✗
Khmer柬埔寨语ខ្មែរ✗
Amharic阿姆哈拉语 (埃塞俄比亚)አማርኛ✗
Belarusian白俄罗斯语беларуская✓
Estonian爱沙尼亚语eesti✓
Swahili斯瓦希里语 (坦桑尼亚)Kiswahili✗
Zulu祖鲁语 (南非)isiZulu✗
Azerbaijani阿塞拜疆语azərbaycanca✗
Armenian亚美尼亚语 (亚美尼亚)Հայերէն✗
Georgian格鲁吉亚语 (格鲁吉亚)ქართული✗
Laotian老挝语 (老挝)ລາວ✗
Mongolian蒙古语Монгол✗
Nepali尼泊尔语नेपाली✗
Kazakh哈萨克语қазақ тілі✗
Galician加利西亚语Galego✗
Icelandic冰岛语íslenska✓
Kannada坎纳达语ಕನ್ನಡ✗
Kyrgyz吉尔吉斯语кыргыз тили; قىرعىز تىلى✗
Malayalam马拉亚拉姆语മലയാളം✗
Marathi马拉提语/马拉地语मराठी✗
Tamil泰米尔语தமிழ்✗
Macedonian马其顿语македонски јазик✗
Telugu泰卢固语తెలుగు✗
Uzbek乌兹别克语Ўзбек тили✗
Basque巴斯克语Euskara✓
Sinhala僧伽罗语 (斯里兰卡)සිංහල✗
Faroese法罗语Føroyskt✗

注意 波斯语的枚举值拼写为 Perisan、葡萄牙语的对照文字为 "Protuguês" (皆为源码中的实际定义，使用时请以源码为准)。

LanguageMapping​

语系类型与语系显示文字的对照辅助 (静态类)。

类型public static class LanguageMapping
源码LanguageMapping.cs

GetLanguageDesc​

public static string GetLanguageDesc(LangType langType)

获取对应的语系文字说明 (详见 LangType 对照表)；未定义对照文字时返回 "Unknown Language"。

string desc = LanguageMapping.GetLanguageDesc(LangType.Spanish); // "Español"