多言語化対応(v0.5.0)設計

日付: 2026-08-01 / ユーザー要望「多言語化対応もお願いします」 実施順: 設定拡充(v0.4.0機能)→ビジュアル刷新(v0.4.0)の後。文言の追加・変更が 落ち着いてから一括スイープすることで手戻りを最小化する。

1. スコープ

• 対象: パネルの全UI文字列(ボタン/ラベル/ヒント/ツールチップ/プレースホルダ/ システムノート/バナー/空状態/ステータス/グループ行 “N tools” 等の書式文字列)
• 対象外: モデル出力・CLI由来の値(モデル名/エラーメッセージ)・ログ内容・ドキュメント (README は日本語のまま。英語版 README.en.md は本件のストレッチ目標)
• 言語: English(既定・フォールバック)/ 日本語。以後の言語追加が1クラス追加で 済む構造にする

2. 機構の選択肢と決定

案	評価
Dictionary<string,string> + Tr("key")	キーのtypoが実行時まで発見できない。キー列挙と実文字列が離れる
型付き文字列テーブル(UiStrings の public readonly フィールド、言語ごとに1インスタンス) ✅	フィールド欠落=コンパイルエラー。呼び出しは L10n.S.AllowButton で補完が効く。リフレクションでパリティ検証が容易
Unity Localization パッケージ	ランタイム向けで依存追加(依存ゼロ方針に反する)。却下
.po / JSON 外部ファイル	エディタ拡張には過剰。ロード失敗系が増える。却下

決定した構造

// Editor/UI/L10n/UiStrings.cs — 全フィールドの器(en の値で初期化した既定)
// Editor/UI/L10n/UiStringsJa.cs — ja の値を流し込むファクトリ
// Editor/UI/L10n/L10n.cs — 現在言語の解決と切替イベント
L10n.S.SettingsTitle          // 使用側。S は現在言語の UiStrings
L10n.F(L10n.S.ToolsGroupFmt, count, secs)  // 書式付き({0} プレースホルダ)

• PanelLanguage { Auto, English, Japanese } を PanelSettings(enum int、YAML安全)に追加。 Auto の解決は遅延(Application.systemLanguage を ctor/フィールド初期化子で 呼ばない — f445c22 の回帰と同じ地雷を踏まない。既存の EnsureCjkUiFontDefault と 同じ OnEnable/初回アクセス経路で解決)
• 言語切替は Settings のドロップダウン(Auto / English / 日本語)。切替時は L10n.LanguageChanged → 開いている AgentPanelWindow / PermissionWindow が UIを再構築(CreateGUI は Phase 3 で再入安全化済み。トランスクリプトDOMは MessageListController.FullRebuild 経由で文字列再評価)
• 文字列連結で文を組み立てない(語順が言語で変わる)。必ず {0} プレースホルダの 書式フィールドにする

3. 回帰ガード

1. パリティテスト: リフレクションで全言語インスタンスの全 string フィールドが 非null・非空であること
2. プレースホルダ整合: 各フィールドについて en と ja の {N} 集合が一致すること (書式引数の食い違いによる実行時 FormatException を封じる)
3. ハードコード再発の抑止: 全ビュー .cs を走査し、new Label(" / text = " 直後の 英字リテラルを検出する source-scan テスト……は誤検知が多すぎるため採用しない。 代わりにレビューチェックリスト(本ノート)+スイープ完了時の実機スクリーンショット (ja/en両方)で担保
4. 既存の GlyphAuditTests(非ASCIIソースバイト検査)と ja テーブルの共存方法を確認 (ja 文字列ファイルは検査対象から除外するか、\uXXXX エスケープにするかを実装時に 判断 — GlyphAuditTests の現仕様を読んで決める。日本語文字列を理由に検査自体を 弱めないこと)

4. 実施計画(ワークフロー)

1. インベントリ: 全 Editor/UI + Integration のユーザー可視文字列を列挙(ファイル別 並列抽出)→ UiStrings フィールド名と en 値の表を確定
2. 機構実装(L10n 3ファイル+PanelSettings+Settings ドロップダウン+再構築配線)
3. ファイル別に置換スイープ(並列可、ファイル単位で独立)
4. ja 翻訳テーブル(UIの文脈を知っている PM がレビュー)
5. サンドボックス全緑 → 実機で ja/en 切替スクリーンショット → リリース v0.5.0