Avalonia：Resx/XML/JSONフォーマットをシームレスにサポートするAvaloniaの多言語ソリューション

はじめに：なぜLang.Avaloniaが必要なのか

クロスプラットフォームUI開発では、多言語サポートはユーザーエクスペリエンスを向上させるためのコアニーズの1つです。Avaloniaは強力なクロスプラットフォームUIフレームワークであり、柔軟な拡張性を備えていますが、ネイティブ多言語ソリューションはフォーマットサポート、開発効率、モジュール化された統合に限界があります。

Lang.Avalonia はAvaloniaフレームワーク用に設計された多言語管理ライブラリで、プラグインアーキテクチャを通じて多言語サポートロジックを再構築し、従来のResxリソースファイルと互換性があるだけでなく、XMLとJSONフォーマットのサポートを追加し、型セーフなリソース参照、動的言語切り替えなどの機能を提供し、多言語開発をより簡単かつ効率的にします。

Lang.Avaloniaを選ぶ理由は？

** マルチフォーマット互換性 **：Resx（伝統的な. NETリソースフォーマット）、XML、JSONの3つの言語ファイルフォーマットをサポートし、異なるプロジェクトのフォーマット設定を満たします。
** 型安全参照 **：T 4テンプレートを通じてC#定数クラスを自動的に生成し、ハードコードされた文字列Keyを避け、コンパイル時にリソース参照エラーを検出できます。
前后台无缝集成：提供XAML标记扩展（{c:I18n}）和C# API双端支持，前台UI绑定与后台逻辑调用同样便捷。
** 動的言語切り替え **：ランタイム言語文化の切り替えをサポートし、アプリケーションを再起動せずにインターフェイステキストをリアルタイムで更新できます。
** モジュール化管理**：プロジェクトモジュール別に言語ファイル（メインモジュール、開発モジュールなど）を分割することをサポートし、大規模プロジェクトのマルチチームコラボレーションに適応します。
** 軽量で簡単な統合 **：プラグイン設計、対応する形式のNuGetパッケージをインストールするだけで、数行のコードで初期化を完了できます。

クイックスタート：インストールと基本構成

ステップ1：NuGetパッケージをインストールする

プロジェクトで使用する言語ファイル形式に応じて、適切なインストールコマンドを選択します。

言語ファイル形式	インストール·コマンド	適用可能なシーン
Resx	`Install-Package Lang.Avalonia.Resx`	従来の. NET Resxリソースファイルに慣れたプロジェクト
XML	`Install-Package Lang.Avalonia.Xml`	手動編集が必要な軽量XML形式のプロジェクトを推奨
JSON	`Install-Package Lang.Avalonia.Json`	最新のフロントエンドスタイルのプロジェクト、エンド間で言語ファイルを共有する必要があるシナリオ

ステップ2：言語ファイルの作成

按规范创建语言文件，建议统一放在项目根目录的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    // 日语

ステップ3：タイプセーフなリソース定数を生成する（T 4テンプレート）

为避免硬编码资源Key（如直接写字符串"SettingView.Title"），通过T4模板自动生成C#常量类，支持编译期校验。

操作ステップ：

从Lang.Avalonia.XX.Demo示例项目中复制对应格式的T4模板（Resx/XML/JSON模板不同），放入项目的i18n文件夹（需自行创建）。
模板会自动扫描i18n文件夹的语言文件，生成语言资源的常量类
言語ファイルにキーが追加/変更されたら、T 4テンプレートを開く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バインディング使用{{ふぉるど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