跳至主要内容

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"