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