Communitygithub.com

AegiNext ローカライズ

AegiNext UI のローカライズを、外部 JSON 言語パック、共有ローカリゼーションサービス、およびライブ Avalonia Loc バインディングを使用して追加、変更、レビュー、デバッグします。翻訳されたコントロール、動的ビューモデルテキスト、メニュー、ウィンドウタイトル、言語設定、言語リソースパッケージに使用します。字幕コンテンツ、ユーザープリセット名、エフェクトスクリプト構文はビジネスデータとしてそのまま保持します。

AegiNext ローカライズ とは?

このスキルは、AegiNext アプリケーションの UI ローカライゼーションを効率的に管理・実装するためのものです。開発者は、`src/AegiNext.Desktop/I18n/` にある統一されたローカリゼーションシステムを利用して、JSON 言語パックの追加・変更、静的・動的テキストのバインド、および言語切り替えを行えます。このシステムは、Avalonia の `Loc` マークアップ拡張によるリアクティブバインディングをサポートし、言語変更時に UI が自動更新されます。また、ワークスペースの変更をコミットせずに、ターゲットを絞った変更が可能で、`en-US` と `zh-CN` の組み込みパックのキーセットを常に一致させる必要があります。ビジネスデータ(字幕、プリセット名など)はローカライズ対象外であり、列挙型からローカライズキーへのマッピングは各機能モジュールに委譲されます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/raphaelstuart/AegiNEXT/tree/HEAD/.agents/skills/aeginext-localization

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

AegiNext ローカライズ は何をしますか?

まず、現在の AegiNext チェックアウトを特定し、実際のコンシューマーと関連コードを読み取ります。リポジトリパスはすべてチェックアウトルートからの相対パスです。開発マシンの絶対パスを実装に書き込まないでください。エントリポイントは src/AegiNext.Desktop/I18n/、名前空間は AegiNext.Desktop.I18n です。ローカリゼーションシステムは統一されており、新しいテキストはこのエントリポイントを使用します。

変更内容に応じたコンテキスト選択

変更内容優先して読み取るファイル
テキスト、言語パック、不足項目、または言語マッチングI18n/Languages/*.json、I18n/Localization.cs、I18n/LocalizationCatalog.cs、I18n/LanguagePackReader.cs
静的コントロールテキスト、ツールチップ、アクセシビリティ名コンシューマーの AXAML、I18n/LocExtension.cs、I18n/XamlNamespace.cs、Controls/Common/IconText.cs
動的ステータス、メニュー、Dock、ウィンドウタイトル該当する ViewModel / コントローラー、Workspace/WorkbenchSession.cs、Windowing/WorkbenchWindowRegistry.cs
初回表示、言語オプション、設定App.axaml.cs、Views/MainWindow.axaml.cs、Workspace/WorkbenchStartupPreferences.cs、Settings/Appearance/AppearanceSettingsViewModel.cs
ビルドまたは公開リソースAegiNext.Desktop.csproj、scripts/publish/AegiNext.Publish.psm1、docs/ja-JP/publishing.md

プロダクションコードのパスは、完全なパスを除き、すべて src/AegiNext.Desktop/ 以下にあります。リポジトリスクリプトとドキュメントはチェックアウトルートから解決されます。完全な規則については、docs/ja-JP/composable-workspace.md のローカリゼーションセクションを参照してください。検証が必要な場合は、references/verification.md を読み取ってください。通常のテキスト変更のためにすべての実装を読み取る必要はありません。

言語パックとキー

ソースファイル I18n/Languages/ を変更します。出力ディレクトリをソースとして扱わないでください。組み込みの en-US.json と zh-CN.json のキーセットは一致している必要があります。新しいキーは両方のバージョンで提供してください。サードパーティ言語は不足項目を許容し、フォールバックを使用します。プレフィックス Workbench、Settings、Preview、Layout、Log、WorkflowLog、WindowChromeProbe を継承します。新しいモジュールは、実際の責任に基づいて名前を付け、意味的に異なるキー(例:Workbench.Export と Settings.Export)を保持します。

{
  "LanguageName": "日本語",
  "LanguageID": "ja-JP",
  "Strings": {
    "Workbench.Cancel": "キャンセル"
  }
}

このスニペットは構造を示すもので、完全な組み込みファイルを置き換えるものではありません。UTF-8 (BOM なし) で保存します。LanguageName は空でなく、LanguageID は有効なカルチャ識別子である必要があり、system は予約された選択値です。Strings のキーは空でなく、値はすべて文字列です。ルートフィールドとテキストキーの重複を拒否します。ID の比較は大文字小文字を区別せず正規化され、テキストキーは大文字小文字を区別します。翻訳内の位置パラメータは、対応するインデックスと書式セマンティクスを保持する必要があります。

起動時は、言語ディレクトリの第1レベルの *.json のみをスキャンし、ファイル内の ID を基準とします。破損したオプションパックは、ファイルを診断して記録した上で除外します。重複 ID の競合グループはすべて除外します。有効かつ一意な en-US が存在しない場合は起動に失敗します。リソースの問題を隠すために C# にテキストのコピーを追加しないでください。リソースの変更または追加後は再起動が必要です。現在のシステムにはホットリロードはありません。

プロジェクトの字幕、ユーザープリセット名、ファイルパス、スクリプトキーワードと構文、シリアル化 ID、エンコーダー識別子は、ビジネス上の意味を保持します。列挙型からテキストキーへのマッピングは、該当するビジネスモジュール(例:Editing/AnimationPropertyLocalization.cs)に配置し、汎用ローカリゼーションサービスを拡張しないでください。

サービス契約と設定

  • Initialize(directory) は UI スレッドで一度だけ呼び出され、元のシステム UI カルチャをキャプチャします。アプリケーションは AXAML をロードする前に、Path.Combine(AppContext.BaseDirectory, "i18n") を使用して初期化します。コントロールやウィンドウごとに初期化を繰り返さないでください。
  • Get(key) はバックグラウンドスレッドで不変のスナップショットを読み取ることができます。優先順位は、現在の言語、en-US、元のキーです。翻訳結果は、呼び出しスレッドの CurrentUICulture に依存しません。非同期再生コールバックもこのエントリポイントを使用します。
  • Format(key, params object[] arguments) は CurrentCulture を使用して数値を書式設定します。言語切り替えは UI カルチャのみを同期し、翻訳によって既存の数値入力カルチャが変更されることはありません。
  • SetLanguage(lang) は UI スレッドでのみ切り替え可能で、インストール済み ID と system をサポートします。未知の ID はパラメータ例外をスローし、現在の言語を維持します。同じ選択と有効状態の場合は、通知を繰り返しません。
  • SelectedLanguageID は要求値、CurrentLanguageID は解決結果です。system が選択されている場合、両者は異なる可能性があります。システムマッチングは初期化時にキャプチャされたカルチャを使用し、正確な ID、親、同じ言語の候補を順に試し、中国語/英語は zh-CN/en-US を優先し、その他の候補は ID でソートし、最後に英語にフォールバックします。
  • KnownLanguages は設定ページで LanguageName を表示し、LanguageID で選択できるようにするために使用され、翻訳された「システムに従う」オプションも含みます。中国語と英語の固定インデックスや設定言語のホワイトリストを復元しないでください。
  • サービスは設定を書き込みません。設定ページは既存の設定保存フローを使用します。メインウィンドウは、自身の AXAML がロードされる前に、同じ読み取り済み起動設定を適用し、同じストア/スナップショットをセッションに渡します。保存された言語パックが一時的に見つからない場合は英語を表示し、元の保存 ID とその他の設定は保持します。
  • 直接 SetLanguage を呼び出した後、テーマ、音量などの無関係な設定を保存しても、現在の言語がリセットされてはなりません。言語設定自体が変更された場合のみ、新しい選択が適用されます。

静的テキストでの Loc の使用

デフォルトの Avalonia XML 名前空間は、アセンブリ XmlnsDefinition を介して LocExtension を既に登録しているため、プレフィックスなしで {Loc Key=...} を直接使用できます。

<TextBlock Text="{Loc Key=Workbench.Codec}" />
<Button Content="{Loc Key=Workbench.Cancel}" />
<Expander Header="{Loc Key=Settings.Advanced}" />
<Button ToolTip.Tip="{Loc Key=Workbench.Save}">
    <common:IconText Text="{Loc Key=Workbench.Save}" IconKey="Save" />
</Button>

最後の例では、xmlns:common="using:AegiNext.Desktop.Controls.Common" が必要です。IconText の既存のアイコン、フォント、行の高さを再利用します。アイコンデンティティは IconKey によって決定され、翻訳キーや翻訳結果から推測してはいけません。Text、Content、Header、ツールチップ、アクセシビリティ名をコントロールプロパティに応じて移行します。まだビジネスバインディングが必要なステータステキストや動的コンテンツを上書きしないでください。

Loc は監視可能なバインディングを返し、最初のサブスクライブ時に現在のテキストを即座に提供し、言語変更後に再プッシュします。ビジネス上の DataContext を保持します。ターゲットコントロールをキャプチャしたり、コントロールツリーをスキャンしたり、翻訳用の Tag を再導入したりしないでください。更新が必要なバインディングを、一回限りの Localization.Get 代入で置き換えないでください。

動的テキストとサブスクリプションのライフサイクル

再生/一時停止、ミュート、ショートカットキー入力、エクスポートステータスなどは、引き続き該当する ViewModel にバインドし、そのリフレッシュロジックで Get / Format を呼び出します。ステータスは、セマンティックキー、列挙型、書式パラメータを保存し、以前に翻訳された文字列のみをキャッシュしてはいけません。セッション、レイアウトコントローラー、ウィンドウレジストラー、設定ウィンドウは、それぞれが所有する動的テキストを集中的にリフレッシュします。まず既存の LanguageChanged 処理エントリポイントを再利用し、同じオブジェクトへの重複サブスクリプションを避けます。

C# で作成されたコントロールは、同じ監視可能なバインディングを使用し、バインディングハンドルを保持および解放します。

var binding = button.Bind(
    ContentControl.ContentProperty,
    Localization.Observe("Workbench.Cancel").ToBinding());

これは Desktop アセンブリ内での使用法であり、Observe は現在 internal です。ウィンドウは Closed / Dispose でハンドルとイベントサブスクリプションを解放します。ステータスバインディングを置き換える前に、古いバインディングを解放します。書式パラメータを持つプロバイダーは、必要なビジネス値のみをキャプチャし、ウィンドウ全体をキャプチャしないでください。Views/TrackStyleChangeDialog.cs を参照してください。固定パネルの一時的なデタッチと最終的な破棄は、既存のライフサイクルに従って区別し、再マウント時に翻訳の更新を失わないようにします。

言語リフレッシュは表示のみを変更し、ビジネスのコミット、プロジェクトの再構築、Undo の実行、または下書きの破棄を呼び出してはいけません。ローカリゼーションオプションリストをリフレッシュする際は、安定した ID、実際の選択値、および元の無効なテキストを保持し、ComboBox の自動選択フィードバックをユーザー編集とみなさないでください。関連パターンについては、Panels/Styles/、Panels/Effects/ の同期 ChoicesRefreshing / ChoicesRefreshed と初期化保護を参照してください。必要なコンシューマーでのみこのパターンを再利用します。

検証と納品

変更範囲に応じて 検証リファレンス を実行し、実際にコンパイルされた AXAML、言語切り替え、ビジネスステータス、および解放動作を確認します。キーの存在は JSON を直接チェックしてください。Get のフォールバック結果を使用して翻訳が完全であることを証明しないでください。ビルド、ロード、または公開ルールを変更する場合は、実際の出力 i18n/、パッケージハッシュ、およびプログラム以外の作業ディレクトリからの起動を確認します。macOS のパッケージパスは AegiNext.app/Contents/MacOS/i18n/ です。

実際に実行したコンパイル/静的解析、テストとスキップ、公開リソース、およびネイティブ検収の証拠を報告してください。テスト数、言語キー数、既存の失敗はすべて、現在の実行結果に基づいて報告し、履歴を検収基準として固定しないでください。ボタンアイコン、長文テキストのレイアウト、およびプラットフォームメニューの最終的な視覚的検収とヘッドレス結果は、それぞれ説明してください。ユーザーの許可範囲を維持し、無関係なワークスペースの変更を保持し、このスキルを使用したことによる自動コミットや依存関係のアップグレードを行わないでください。

関連スキル