Lang.Avalonia：Avalonia多語言解決方案，無縫支援Resx/XML/JSON三種格式

引言：為什麼需要Lang.Avalonia？

在跨平台UI開發中，多語言支援是提升使用者體驗的核心需求之一。Avalonia作為一款強大的跨平台UI框架，雖具備靈活的擴充性，但原生多語言方案在格式支援、開發效率和模組化整合上存在侷限。

Lang.Avalonia 應運而生——這是一款專為Avalonia框架設計的多語言管理程式庫，透過插件化架構重構了多語言支援邏輯，不僅相容傳統Resx資源檔案，還新增XML和JSON格式支援，同時提供型別安全的資源參照、動態語言切換等能力，讓多語言開發更簡單、更高效。

核心特性：為什麼選擇Lang.Avalonia？

多格式相容：支援Resx（傳統.NET資源格式）、XML、JSON三種語言檔案格式，滿足不同專案的格式偏好。
型別安全參照：透過T4範本自動產生C#常數類別，避免硬編碼字串Key，編譯期即可偵測資源參照錯誤。
前後台無縫整合：提供XAML標記延伸（{c:I18n}）和C# API雙端支援，前台UI繫結與後台邏輯呼叫同樣便捷。
動態語言切換：支援執行時切換語言文化，無需重啟應用程式即可即時更新介面文字。
模組化管理：支援依專案模組拆分語言檔案（如主模組、開發模組），適配大型專案的多團隊協作。
輕量易整合：插件化設計，僅需安裝對應格式的NuGet套件，幾行程式碼即可完成初始化。

快速開始：安裝與基礎設定

第一步：安裝NuGet套件

根據專案使用的語言檔案格式，選擇對應的安裝命令：

語言檔案格式	安裝命令	適用情境
Resx	`Install-Package Lang.Avalonia.Resx`	習慣傳統.NET Resx資源檔案的專案
XML	`Install-Package Lang.Avalonia.Xml`	偏好輕量XML格式、需手動編輯的專案
JSON	`Install-Package Lang.Avalonia.Json`	現代前端風格專案、需跨端共享語言檔案的場景

第二步：建立語言檔案

依規範建立語言檔案，建議統一放在專案根目錄的i18n資料夾中，檔案命名需包含文化識別（如zh-CN代表簡體中文，en-US代表美式英語）。

Resx格式

Resx檔案需以基礎檔案名（如Resources.resx）+ 文化識別（可選）命名，基礎檔案預設為 fallback 語言，具體參考範例專案：

i18n/Resources.resx          // 預設語言（如英語）
i18n/Resources.zh-CN.resx    // 簡體中文
i18n/Resources.zh-Hant.resx  // 繁體中文
i18n/Resources.ja-JP.resx    // 日語

XML格式

XML檔案直接以文化識別命名，每個檔案獨立儲存對應語言的資源：

i18n/en-US.xml    // 美式英語
i18n/zh-CN.xml    // 簡體中文
i18n/zh-Hant.xml  // 繁體中文
i18n/ja-JP.xml    // 日語

JSON格式範例

JSON檔案同樣以文化識別命名，採用鍵值對結構儲存資源：

i18n/en-US.json    // 美式英語
i18n/zh-CN.json    // 簡體中文
i18n/zh-Hant.json  // 繁體中文
i18n/ja-JP.json    // 日語

第三步：產生型別安全的資源常數（T4範本）

為避免硬編碼資源Key（如直接寫字串"SettingView.Title"），透過T4範本自動產生C#常數類別，支援編譯期驗證。

操作步驟：

從Lang.Avalonia.XX.Demo範例專案中複製對應格式的T4範本（Resx/XML/JSON範本不同），放入專案的i18n資料夾（需自行建立）。
範本會自動掃描i18n資料夾的語言檔案，產生語言資源的常數類別。
當語言檔案新增/修改Key後，打開T4範本按Ctrl + S可重新產生。

實戰使用：前後台整合指南

初始化多語言管理器

在應用程式啟動時（建議在App.axaml.cs的Initialize方法中）初始化多語言管理器，預載入語言資源：

// 引入命名空間
using Lang.Avalonia;
using Lang.Avalonia.Resx; // 對應格式的命名空間（Resx/Xml/Json）
using System.Globalization;

public override void Initialize()
{
    base.Initialize();
    // 初始化Resx格式（其他格式替換為XmlLangPlugin/JsonLangPlugin）
    I18nManager.Instance.Register(
        plugin: new ResxLangPlugin(),  // 格式插件
        defaultCulture: new CultureInfo("zh-CN"),  // 預設語言
        error: out var error  // 錯誤訊息（可選）
    );
    if (!string.IsNullOrEmpty(error))
    {
        // 處理初始化錯誤（如檔案不存在）
        Console.WriteLine($"多語言初始化失敗：{error}");
    }
}

前台XAML繫結使用

透過{c:I18n}標記延伸在AXAML中繫結資源，支援直接參照T4產生的常數類別，還可指定特定語言：

<!-- 引入命名空間 -->
xmlns:c="https://codewf.com"  <!-- Lang.Avalonia的標記延伸命名空間 -->
xmlns:mainLangs="clr-namespace:Localization.Main"  <!-- 主模組常數類別 -->
xmlns:developModule="clr-namespace:Localization.DevelopModule"  <!-- 開發模組常數類別 -->

<!-- 繫結目前預設語言的資源 -->
<SelectableTextBlock Text="{c:I18n {x:Static mainLangs:SettingView.Title}}" />

<!-- 強制指定語言（如簡體中文） -->
<SelectableTextBlock 
    Text="{c:I18n {x:Static developModule:Title2SlugView.Title}, CultureName=zh-CN}" 
/>

後台C#邏輯使用

透過I18nManager.Instance.GetResource方法在後台程式碼中取得資源，支援取得目前語言或指定語言的文字：

// 引入產生的常數命名空間
using Localization.Main;

// 取得目前預設語言的資源
var titleCurrent = I18nManager.Instance.GetResource(MainView.Title);

// 取得指定語言的資源（簡體中文）
var titleZhCN = I18nManager.Instance.GetResource(MainView.Title, "zh-CN");

// 取得指定語言的資源（美式英語）
var titleEnUS = I18nManager.Instance.GetResource(MainView.Title, "en-US");

進階技巧：動態切換語言

執行時切換語言只需設定屬性I18nManager.Instance.Culture，介面會自動更新：

// 切換為英語
I18nManager.Instance.Culture = new CultureInfo("en-US");

// 切換為日語
I18nManager.Instance.Culture = new CultureInfo("ja-JP");

注意事項與最佳實踐

文化識別規範：統一使用zh-CN（簡體中文）、en-US（美式英語）等標準文化名稱，避免混用zh_CN等非標準格式。
模組化拆分：大型專案建議依功能模組拆分語言檔案（如主模組、使用者模組），T4範本會自動產生對應模組的常數類別，避免Key衝突。
Fallback機制：當指定語言的資源不存在時，會自動 fallback 到預設語言（初始化時指定的defaultCulture），建議保留預設語言檔案作為兜底。
效能最佳化：語言資源會在初始化時快取，適合頻繁切換語言的場景；若語言檔案較大，可考慮非同步載入（需結合Avalonia的非同步初始化機制）。

結語

Lang.Avalonia透過插件化設計、多格式支援和型別安全特性，大幅簡化了Avalonia專案的多語言開發流程。無論是傳統Resx使用者，還是偏好XML/JSON的現代專案，都能快速整合並享受高效的多語言管理體驗。

若在使用中遇到問題或需要擴充新格式，可參考Lang.Avalonia的插件介面實作自訂語言插件，也歡迎參與專案貢獻！

倉庫地址：https://github.com/dotnet9/Lang.Avalonia