laravel-i18n

Laravelのローカライズについて説明します。PHPとJSONの翻訳ファイル、複数形のルール、Bladeの翻訳ヘルパー、ロケール検出ミドルウェア、日付・数値・通貨のフォーマット、ベンダーパッケージの翻訳、大規模アプリ向けの翻訳の整理を取り上げます。Laravel 13での`Context::add()`を使った、キューで安全にロケールを伝播する方法も含まれます。

Laravelの国際化

エージェントのワークフロー（必須）

実装を始める前に、次の3つのエージェントをそれぞれ1回のAgent呼び出しで、並行して起動してください。各呼び出しにはnameを指定します。

1. fuse-ai-pilot:explore-codebase - 既存の翻訳パターンを確認します
2. fuse-ai-pilot:research-expert - Context7を使ってLaravelのi18nのベストプラクティスを確認します
3. mcp__context7__query-docs - Laravelのローカライズに関するドキュメントを確認します

実装後、検証のためにfuse-ai-pilot:sniperを実行してください。

---

概要

機能	PHPファイル	JSONファイル
キー	短い（messages.welcome）	全文
ネスト	対応	フラットのみ
最適な用途	構造化された翻訳	大規模アプリ

---

重要なルール

1. 文字列を連結しないでください - :placeholderによる置換を使います
2. 複数形ではゼロを必ず処理してください
3. 機能ごとにグループ化してください - auth.login.title、auth.login.button
4. 文字列は早めに抽出してください - ビューにハードコードしたテキストを残さないでください
5. ロケールを検証してください - enumまたは許可リストを使います

---

選択ガイド

Translation task?
├── Basic string → __('key')
├── With variables → __('key', ['name' => $value])
├── Pluralization → trans_choice('key', $count)
├── In Blade → @lang('key') or {{ __('key') }}
├── Locale detection → Middleware
├── Format date/money → LocalizationService
└── Package strings → trans('package::key')

---

リファレンスガイド

概念（理由とアーキテクチャ）

トピック	リファレンス	参照するタイミング
セットアップ	localization.md	初期設定
複数形	pluralization.md	数に応じた翻訳
Blade	blade-translations.md	ビューの翻訳
ミドルウェア	middleware.md	ロケール検出
フォーマット	formatting.md	日付・数値・通貨
パッケージ	packages.md	ベンダー翻訳
ベストプラクティス	best-practices.md	大規模アプリの整理

テンプレート（コード全体）

テンプレート	使用するタイミング
SetLocaleMiddleware.php.md	URL／セッションによるロケール検出
lang-files.md	翻訳ファイルの例
LocaleServiceProvider.php.md	ローカライズサービスの一元管理
LocaleRoutes.php.md	URLプレフィックスによるロケールルーティング

---

クイックリファレンス

// Basic translation
__('messages.welcome')

// With replacement
__('Hello :name', ['name' => 'John'])

// Pluralization
trans_choice('messages.items', $count)

// Runtime locale
App::setLocale('es');
App::currentLocale();  // 'es'

---

ベストプラクティス

推奨事項

• 動的な値には:placeholderを使います
• 複数形ではゼロの場合を処理します
• キーを機能モジュールごとにグループ化します
• 型安全性のためにLocale enumを使います
• ミドルウェアでCarbonのロケールを設定します

非推奨事項

• 翻訳済みの文字列を連結しないでください
• ビューにテキストをハードコードしないでください
• 検証せずに任意のロケールを受け入れないでください
• DBベースの翻訳を作成しないでください（ファイルを使います）

---

Laravel 13に関する注意事項

ローカライズAPI（__()、trans_choice()、App::setLocale()）はLaravel 13でも変更されていません。具体的な注意点は次のとおりです。

• Context::add('locale', $locale)はキューに登録されたジョブへロケールを伝播します（ShouldQueueジョブでロケールが失われていたL12のバグを修正します）
• cache.serializable_classes（L13ではデフォルトでfalse）：Localeオブジェクトをキャッシュする場合は、一覧に追加してください
• SetLocaleミドルウェアは、[[laravel-auth]]の新しいPreventRequestForgeryミドルウェアと互換性があります

// app/Jobs/SendNotification.php
public function handle(): void
{
    App::setLocale(Context::get('locale', 'en'));
    Notification::send($this->user, new OrderShipped());
}