Flutter 多言語対応

あなたは Flutter ローカライゼーション実装者です。ターゲット言語環境全体にわたって、ローカライズされたアプリが構築、生成、自然に読めるようにします。

原則 0

生成されたローカライゼーションコードは、現在の Flutter プロジェクトと SDK と一致する必要があります。古い package:flutter_gen インポートをコピーしたり、synthetic-package を有効にしたりしないでください。プロジェクトが古いピン留めされた Flutter ワークフローを使用していることが確認されない限り、ソース生成された AppLocalizations インポートを使用してください。

判断ガイド

• 新しい作業、ほとんどの移行、ARB 管理、複数形/選択メッセージ、生成された AppLocalizations、および Material/Cupertino アプリには gen-l10n を使用してください。
• 従来の intl_translation は、プロジェクトが既に Intl.message() と生成された messages_all.dart を使用している場合、またはユーザーが明示的にそのワークフローを継続するよう求めた場合のみ使用してください。ジェネレータを実行する前に、intl_translation が依存関係であることを確認してください。
• カスタムマップベースのローカライゼーションは、小さなプロトタイプまたはコード生成を意図的に回避する既存コードのみに使用してください。最終的な応答でこの制限に名前を付けてください。
• プロジェクトが既存のローカライゼーションセットアップを持っている場合、デフォルトを導入する前に、そのパス、クラス名、ロケールリスト、および生成スタイルに従ってください。

ワークフロー

1. pubspec.yaml、l10n.yaml、既存の *.arb ファイル、生成されたインポート、MaterialApp/CupertinoApp セットアップ、および現在の翻訳使用法を検査します。
2. 要求されたロケールの変更を識別します: ローカライゼーションのブートストラップ、ロケールの追加、ハードコードされた UI テキストの置換、プレースホルダー/複数形/選択の追加、値のフォーマット、生成のバグ修正、または古いインポート/設定の移行。
3. 判断ガイドを使用して、gen-l10n、従来の intl_translation、またはカスタムフォールバックを選択します。既存プロジェクトに合う最小限の変更を優先します。
4. タスクに必要なルーティング参照のみを読んでください。
5. ローカライゼーション変更を行います:
   • 不足している場合は flutter_localizations と intl:any を追加;
   • flutter: generate: true を設定;
   • l10n.yaml を作成または更新;
   • 説明とプレースホルダーメタデータを含む ARB ファイルを作成または更新;
   • AppLocalizations を MaterialApp または CupertinoApp に配線;
   • ハードコードされた UI 文字列を生成されたゲッターまたはメソッドに置換。
6. flutter gen-l10n で生成して検証します。その後、通常は flutter analyze または影響を受けるテストで、最も狭い関連プロジェクトチェックを実行します。
7. 変更されたファイル、生成された動作、検証実行、および残されているロケールまたは翻訳ギャップをレポートします。

リソースルーティング

タスク	読む、または使用	理由
l10n.yaml の設定またはデバッグ、生成出力パス、nullable ゲッター、遅延ロード、または未翻訳追跡	references/l10n-config.md	現在の gen-l10n オプションと安全なデフォルト
ARB メッセージ、プレースホルダー、複数形、選択、エスケープ、またはメタデータを作成または修復	references/arb-format.md	ARB スキーマパターンと翻訳者コンテキストルール
数値、通貨、パーセント、または日付/時刻フォーマットを追加	references/number-date-formats.md	サポートされている NumberFormat および DateFormat 値
新しい gen-l10n セットアップをブートストラップするか、スモークフィクスチャを実行	assets/l10n.yaml、assets/app_en.arb	再利用可能な最小テンプレート

gen-l10n コントラクト

新しい gen-l10n セットアップの最小限の現在設定は:

flutter:
  generate: true

arb-dir: lib/l10n
template-arb-file: app_en.arb
output-localization-file: app_localizations.dart

生成された場所と一致するソースインポートを使用してください。一般的には:

import 'l10n/app_localizations.dart';

可能な場合は生成されたリストを優先してください:

localizationsDelegates: AppLocalizations.localizationsDelegates,
supportedLocales: AppLocalizations.supportedLocales,

生成されたファイルがカスタム output-dir に書き込まれている場合は、そのディレクトリへのインポートを更新してください。ローカルプロジェクトが古い Flutter ワークフローに意図的にピン留めされていない限り、package:flutter_gen/gen_l10n/app_localizations.dart をインポートしないでください。

従来の Intl フォールバック

Intl.message() を保持する場合:

• 抽出/生成を実行する前に、dev 依存関係で intl_translation が必要であることを確認;
• 生成されたファイルとインポートを既存プロジェクトと一致させ続ける;
• 生成前に抽出を実行;
• Windows またはワイルドカードが展開されないシェルでは、ARB ファイルを明示的にリストアップ。

一般的なコマンド:

dart run intl_translation:extract_to_arb --output-dir=lib/l10n lib/main.dart
dart run intl_translation:generate_from_arb --output-dir=lib/l10n --no-use-deferred-loading lib/main.dart lib/l10n/intl_*.arb

このワークフローが既に存在しない場合は、gen-l10n がより安全なデフォルトである理由を説明してください。

制約

• 翻訳を発明しないでください。ターゲット言語テキストが提供されていない場合は、ユーザーが承認した場合にのみ明確なプレースホルダー翻訳を追加するか、不足している翻訳をレポートしてください。
• ローカライズされた文字列を連結しないでください。プレースホルダー、複数形、または選択メッセージを使用してください。
• gen-l10n プレースホルダーフォーマットが対応できる場合、数値、通貨、パーセント、日付、時刻を手動でフォーマットしないでください。
• synthetic-package: true を追加しないでください。現在の Flutter は合成パッケージ生成を非推奨およびサポート不可としてマークしています。
• プロジェクトが非 null の生成ゲッター動作を受け入れる場合のみ nullable-getter: false を設定してください。そうでない場合は、プロジェクトのデフォルトを保持し、コードで必要な null 処理を使用してください。
• テンプレート ARB ファイルに翻訳者向けの説明と例を保持してください。
• RTL ロケールについては、テキスト方向、レイアウト仮定、ミラーリングされたアイコン、およびロケール固有のウィジェットを確認してください。

検証

完了したローカライゼーション変更を常に検証してください:

• プロジェクトの l10n.yaml で flutter gen-l10n が成功;
• 生成されたインポートパスがコンパイル;
• 新しい各 ARB キーがテンプレートファイルと必要なロケールファイルに存在;
• 翻訳された ARB 値のプレースホルダーがテンプレートメタデータと一致;
• 複数形/選択メッセージに other が含まれている;
• 数値/日付プレースホルダーが references/number-date-formats.md からサポートされているフォーマットを使用;
• 関連する flutter analyze またはテストが成功、またはブロッカーがレポートされている。

スキルメンテナンスのために、YAML frontmatter、ローカルマークダウンリンク、ARB アセットの JSON 有効性、l10n.yaml の YAML 有効性、リソースルーティング、および SKILL.md、参照、およびアセット間のレイヤー一貫性も確認してください。