internationalization

国際化

Flutter の組み込みローカライズシステムを使用する Flutter アプリケーションにおける、ARB ファイルを唯一の信頼できる情報源とする国際化（i18n）とローカライズ（l10n）のベストプラクティスです。

基本規則

すべての国際化作業に、以下の規則を適用してください。

• ユーザーに表示する文字列をハードコードしないでください — すべてのテキストは l10n システムを通してください
• Flutter の組み込みローカライズシステムを使用してください — flutter_localizations と intl を使用し、サードパーティ製の i18n ライブラリは使用しないでください
• ARB ファイルをすべての翻訳の唯一の信頼できる情報源にしてください
• より簡潔に l10n にアクセスできるよう、BuildContext 拡張を使用してください — AppLocalizations.of(context) の代わりに context.l10n を使用してください
• 再利用可能なウィジェットには、ローカライズ済みの文字列をパラメーターとして渡してください — 共有ウィジェットを AppLocalizations に直接依存させないでください
• EdgeInsets（left/right）の代わりに EdgeInsetsDirectional（start/end）を使用してください — RTL 言語でも正しいレイアウトになります
• RTL レイアウトを適切に処理してください — パディング、配置、整列には方向対応のウィジェットを使用してください
• 早い段階で i18n を実装してください — 最初は 1 言語のみの予定でも、追加の作業はわずかで、長期的なメリットは大きくなります
• Dart 3.13 のプライマリーコンストラクター — Dart 3.13 以降を基準とする場合、再利用可能なウィジェットのローカライズ済み文字列フィールドは、this.field ではなく、プライマリーコンストラクターの宣言パラメーターとして宣言してください（class const ConfirmDialog({required final String title, super.key}) extends StatelessWidget）。従来の形式は 3.13 より前の場合にのみ使用してください

セットアップ手順と ARB ファイル形式

依存関係として flutter_localizations と intl を追加し、pubspec.yaml で generate: true を有効にして、l10n.yaml を設定し、lib/l10n/arb/ に ARB ファイルを作成してから、flutter gen-l10n を実行し、localizationsDelegates と supportedLocales を使用して MaterialApp を設定します。ARB ファイルは、単純な文字列、プレースホルダー、ICU の複数形構文に対応しています。

BuildContext 拡張

コードベース全体で簡潔に l10n にアクセスできるよう、拡張を作成してください。

extension AppLocalizationsX on BuildContext {
  AppLocalizations get l10n => AppLocalizations.of(this);
}

使用例：

// Preferred
Text(context.l10n.helloWorld);

// Avoid
Text(AppLocalizations.of(context).helloWorld);

再利用可能なウィジェットの方針

別のパッケージにある共有ウィジェットは、AppLocalizations に直接依存させないでください。代わりに、ローカライズ済みの文字列をコンストラクターパラメーターとして渡します。

共有パッケージに AppLocalizations を追加してほしいと依頼された場合は、追加を断り、その理由（パッケージ独自の翻訳を抱えることになり、それを利用するすべてのアプリがその翻訳に固定されること）を説明してください。そのうえで、ラベルを final String コンストラクターパラメーターとして受け取るウィジェットに書き換え、呼び出し側で context.l10n を渡す例を示してください。両方とも Dart コードで示してください。変更を文章だけで説明すると、呼び出し側がシグネチャーを推測しなければならなくなります。

// Shared widget — no l10n dependency
class const ConfirmDialog({
  required final String title,
  required final String message,
  required final String confirmLabel,
  required final String cancelLabel,
  super.key,
}) extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AlertDialog(
      title: Text(title),
      content: Text(message),
      actions: [
        TextButton(onPressed: () => Navigator.pop(context), child: Text(cancelLabel)),
        FilledButton(onPressed: () => Navigator.pop(context, true), child: Text(confirmLabel)),
      ],
    );
  }
}

// App-level usage — passes localized strings
showDialog<bool>(
  context: context,
  builder: (_) => ConfirmDialog(
    title: context.l10n.deleteTitle,
    message: context.l10n.deleteMessage,
    confirmLabel: context.l10n.confirm,
    cancelLabel: context.l10n.cancel,
  ),
);

テキストの方向性

すべてのパディングとマージンに、EdgeInsets（left/right）ではなく EdgeInsetsDirectional（start/end）を使用してください。RTL に対応したレイアウトには、方向対応のウィジェット（PositionedDirectional、AlignDirectional、BorderDirectional）を使用してください。アイコンは RTL で自動的に反転しますが、画像には matchTextDirection: true が必要です。

バックエンドに関する考慮事項

バックエンドのコンテンツはロケールごとの翻訳とともに保存し、クライアントがユーザーのロケールを送信するようにしてください。エラーメッセージについては、HTTP ステータスコードまたはカスタムのバックエンドエラー定数をフロントエンドで l10n キーに対応付けてください。

よくあるパターン

新しいロケールの追加

1. lib/l10n/arb/ に app_<locale>.arb を作成します（例：app_fr.arb）
2. テンプレート ARB ファイルにあるすべてのキーの翻訳を追加します
3. flutter gen-l10n を実行します
4. 新しいロケールは AppLocalizations.supportedLocales から自動的に利用できるようになります

新しい文字列の追加

1. テンプレート ARB ファイル（app_en.arb）にキーと値のペアを追加します
2. 必要に応じて、説明とプレースホルダーを含む @key メタデータを追加します
3. ほかのすべての ARB ファイルに翻訳を追加します
4. flutter gen-l10n を実行します
5. context.l10n.newKey を使用します

複数形処理

1. ICU メッセージ構文を使用して、テンプレート ARB ファイルに複数形の文字列を定義します
2. "type": "int" を含むプレースホルダーメタデータを指定します
3. すべてのロケールの ARB ファイルに複数形を追加します
4. context.l10n.itemCount(items.length) を使用します

追加リソース

• references/setup.md — セットアップ手順の全工程とARBファイル形式の例
• references/directionality.md — 視覚的ウィジェットと方向性を持つウィジェット、アイコン／画像の反転、Materialの双方向性基準
• references/backend.md — 多言語コンテンツの保存とエラーメッセージのローカライズ