Lang.Avalonia：Avalonia多言語ソリューション、Resx/XML/JSONの3形式をシームレスにサポート

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

クロスプラットフォームUI開発において、多言語対応はユーザー体験を向上させる中核的な要件の一つです。Avaloniaは強力なクロスプラットフォームUIフレームワークであり、柔軟な拡張性を備えていますが、ネイティブの多言語ソリューションには、フォーマットサポート、開発効率、モジュール化統合の面で制限があります。

Lang.Avalonia は、Avaloniaフレームワーク向けに設計された多言語管理ライブラリです。プラグインアーキテクチャにより多言語サポートのロジックを再構築し、従来のResxリソースファイルに加え、XMLおよびJSONフォーマットをサポートします。また、タイプセーフなリソース参照や動的な言語切り替えなどの機能を提供し、多言語開発をよりシンプルかつ効率的にします。

コア機能：なぜLang.Avaloniaを選ぶのか？

マルチフォーマット対応：Resx（従来の.NETリソースフォーマット）、XML、JSONの3つの言語ファイル形式をサポートし、プロジェクトのフォーマット選好に対応します。
タイプセーフな参照：T4テンプレートにより自動生成されたC#定数クラスを使用することで、ハードコードされた文字列キーを回避し、コンパイル時にリソース参照の誤りを検出できます。
フロントエンド/バックエンドのシームレスな統合：XAMLマークアップ拡張（{c:I18n}）とC# APIの両方を提供し、UIバインディングとバックエンドロジック呼び出しの両方で容易に利用できます。
動的言語切り替え：実行時に言語カルチャを切り替えることができ、アプリケーションを再起動せずに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）+ カルチャ識別子（オプション）で命名します。ベースファイルはフォールバック言語として扱われます。詳細はサンプルプロジェクトを参照してください。

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：タイプセーフなリソース定数の生成（T4テンプレート）

リソースキーをハードコード（例：文字列 "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 を設定するだけで、UIは自動的に更新されます。

// 英語に切り替え
I18nManager.Instance.Culture = new CultureInfo("en-US");

// 日本語に切り替え
I18nManager.Instance.Culture = new CultureInfo("ja-JP");

注意事項とベストプラクティス

カルチャ識別子の標準化：zh-CN（簡体字中国語）、en-US（アメリカ英語）などの標準カルチャ名を使用し、zh_CN などの非標準形式は避けてください。
モジュール分割：大規模プロジェクトでは、機能モジュールごとに言語ファイルを分割（例：メインモジュール、ユーザーモジュール）することを推奨します。T4テンプレートは自動的に対応するモジュールの定数クラスを生成し、キーの衝突を防ぎます。
フォールバック機構：指定された言語のリソースが存在しない場合、自動的にデフォルト言語（初期化時に指定した defaultCulture）にフォールバックします。デフォルト言語ファイルは常に保持しておくことを推奨します。
パフォーマンス最適化：言語リソースは初期化時にキャッシュされるため、頻繁に言語を切り替えるシナリオに適しています。言語ファイルが大きい場合は、非同期読み込みを検討してください（Avaloniaの非同期初期化機構と組み合わせる必要があります）。

おわりに

Lang.Avaloniaは、プラグイン設計、マルチフォーマット対応、タイプセーフな機能により、Avaloniaプロジェクトの多言語開発プロセスを大幅に簡素化します。従来のResxユーザーでも、XMLやJSONを好むモダンなプロジェクトでも、迅速に統合し、効率的な多言語管理体験を享受できます。

問題が発生した場合や新しいフォーマットを拡張する必要がある場合は、Lang.Avaloniaのプラグインインターフェースを参照してカスタム言語プラグインを実装できます。プロジェクトへのコントリビュートも歓迎します。

リポジトリURL：https://github.com/dotnet9/Lang.Avalonia