AegiNext ローカライゼーション
現在のAegiNextチェックアウトを特定し、実際のコンシューマーコードと関連コードを最初に読んでください。リポジトリパスはそのチェックアウトを基準に解決し、開発者マシンのパスを埋め込まないでください。共有エントリポイントは src/AegiNext.Desktop/I18n/ で、名前空間は AegiNext.Desktop.I18n です。新しいUIテキストには、この既存のシステムを拡張してください。
変更のためのコンテキストを選択
| 変更内容 | 最初に読むファイル |
|---|---|
| テキスト、言語パック、欠落エントリ、言語マッチング | 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/en/publishing.md |
完全なプレフィックスがないプロダクションパスは src/AegiNext.Desktop/ 以下にあります。スクリプトとドキュメントはチェックアウトルートから解決されます。ワークスペースのローカライゼーションについては docs/en/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": "English",
"LanguageID": "en-US",
"Strings": {
"Workbench.Cancel": "Cancel"
}
}
これはスキーマを示すものであり、組み込みパックを置き換えるものではありません。UTF-8 BOMなしで保存してください。LanguageName は非空、LanguageID は有効なカルチャ識別子であり、非空の Strings キーはすべて文字列にマップされる必要があります。system は選択値として予約されています。重複するルートフィールドとテキストキーを拒否してください。言語IDは正規化され、大文字小文字を区別せずに比較されます。テキストキーは大文字小文字を区別します。翻訳内の位置引数インデックスと書式設定のセマンティクスを保持してください。
起動時は、最初のレベルの *.json ファイルのみをスキャンし、その内部IDを使用します。不正な形式のオプションパックはファイル診断を生成し、除外されます。重複IDを持つグループ内のすべてのパックは除外されます。有効で一意の en-US パックがない場合、起動は失敗します。重複するC#テキストテーブルでリソースの失敗を隠蔽しないでください。リソースの変更には再起動が必要です。このシステムにホットリロードはありません。
字幕コンテンツ、ユーザープリセット名、パス、スクリプト構文、シリアル化されたID、エンコーダーIDは、そのビジネス上の意味を保持します。Enumからキーへのマッピングは、一般的なサービスを拡張するのではなく、機能に属します(例:Editing/AnimationPropertyLocalization.cs)。
サービスと設定の契約
Initialize(directory)を、AXAMLをロードする前にUIスレッドで1回だけ呼び出してください。Path.Combine(AppContext.BaseDirectory, "i18n")を使用します。これにより、元のシステムUIカルチャがキャプチャされます。コントロール/ウィンドウごとに初期化しないでください。Get(key)は、任意のスレッドから不変のスナップショットを読み取ります。現在の言語、次にen-US、最後に生のキーを試します。結果は呼び出し元のCurrentUICultureに依存しません。非同期再生コールバックは同じサービスを使用します。Format(key, params object[] arguments)は、数値の書式設定にCurrentCultureを使用します。言語変更によりUIカルチャは更新されますが、確立された数値入力カルチャは変更されません。SetLanguage(lang)はUIスレッドで実行され、インストールされているIDまたはsystemを受け入れます。不明なIDはスローを発生させ、言語は変更されません。選択/有効な状態が変更されていない場合は、再度通知しません。SelectedLanguageIDは要求された選択であり、CurrentLanguageIDは解決されたパックです。システムマッチングは最初にキャプチャされたカルチャを使用します。正確なID、親、同じ言語の候補、英語の順に試します。中国語/英語はzh-CN/en-USを優先します。その他の候補はIDでソートされます。KnownLanguagesはLanguageNameラベルとLanguageID選択を提供し、さらにローカライズされたシステムオプションを提供します。固定の英語/中国語インデックスや設定のホワイトリストを復元しないでください。- サービスは設定を永続化しません。MainWindow 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の再導入、ライブバインディングの1回限りのGet割り当てによる置き換えは行わないでください。
動的テキストとサブスクリプションのライフタイム
再生/一時停止、ミュート、ショートカット録画、エクスポート状態は、それぞれのViewModelにバインドされたままにし、それらは Get/Format を呼び出します。最後に翻訳された文字列だけでなく、セマンティックキー、Enum、書式引数を保存してください。セッション、レイアウト、レジストリ、設定で一元化されたLanguageChangedハンドラを再利用し、重複したサブスクリプションは避けてください。
プログラムによるコントロールの場合は、オブザーバブルバインディングハンドルを保持して解放してください。
var binding = button.Bind(
ContentControl.ContentProperty,
Localization.Observe("Workbench.Cancel").ToBinding());
Observe は現在Desktop内部のものです。ハンドル/イベントはClosed/Disposeで解放し、置き換えられた状態バインディングは最初に破棄してください。プロバイダーは、Views/TrackStyleChangeDialog.cs のように、必要なビジネス値のみをキャプチャします。一時的な固定パネルのデタッチと最終的な破棄を区別し、再アタッチ時にも更新が受け取られるようにしてください。
言語リフレッシュはプレゼンテーションのみを変更します。ビジネスコミット、プロジェクトの再作成、Undo、破棄されたドラフトは発生しません。安定したID、実際の選択、無効な生入力を維持しながら選択リストをリフレッシュし、フレームワークの自動選択をユーザー編集として無視してください。必要に応じて、消費側のStyles/Effects ChoicesRefreshing/ChoicesRefreshedガードを再利用してください。
検証と配信
検証 の影響を受けるグループに従い、コンパイルされたAXAML、ライブスイッチング、ビジネス状態、リリース動作を確認してください。生のJSONでキーの完全性を検査してください。Getのフォールバックは翻訳の存在を証明できません。ビルド/ロード/公開の変更には、実際の出力i18nディレクトリ、パッケージハッシュ、別の作業ディレクトリからの起動が必要です。macOSパッケージは AegiNext.app/Contents/MacOS/i18n/ を使用します。
実際のビルド/分析、合格/失敗/スキップされたテスト、リソースチェック、ネイティブ受け入れを報告してください。キー/テストのカウントは履歴の合計ではなく、現在の証拠から再集計してください。Headlessの結果と、ボタン/アイコン、長文テキスト、プラットフォームメニューの外観を分けて報告してください。スコープと関連のない作業を保持してください。このスキルを使用しても、コミットや依存関係のアップグレードは許可されません。