laravel-i18n

Covers Laravel localization: PHP vs JSON translation files, pluralization rules, Blade translation helpers, locale-detection middleware, date/number/ currency formatting, vendor package translations, and organizing translations for large apps. Includes queue-safe locale propagation via Context::add() in Laravel 13.

Laravel Internationalization

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Check existing translation patterns
2. fuse-ai-pilot:research-expert - Verify Laravel i18n best practices via Context7
3. mcp__context7__query-docs - Check Laravel localization documentation

After implementation, run fuse-ai-pilot:sniper for validation.

---

Overview

Feature	PHP Files	JSON Files
Keys	Short (messages.welcome)	Full text
Nesting	Supported	Flat only
Best for	Structured translations	Large apps

---

Critical Rules

1. Never concatenate strings - Use :placeholder replacements
2. Always handle zero in pluralization
3. Group by feature - auth.login.title, auth.login.button
4. Extract strings early - No hardcoded text in views
5. Validate locales - Use enum or whitelist

---

Decision Guide

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')

---

Reference Guide

Concepts (WHY & Architecture)

Topic	Reference	When to Consult
Setup	localization.md	Initial configuration
Pluralization	pluralization.md	Count-based translations
Blade	blade-translations.md	View translations
Middleware	middleware.md	Locale detection
Formatting	formatting.md	Date/number/currency
Packages	packages.md	Vendor translations
Best Practices	best-practices.md	Large app organization

Templates (Complete Code)

Template	When to Use
SetLocaleMiddleware.php.md	URL/session locale detection
lang-files.md	Translation file examples
LocaleServiceProvider.php.md	Centralized localization service
LocaleRoutes.php.md	URL prefix locale routing

---

Quick Reference

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

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

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

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

---

Best Practices

DO

• Use :placeholder for dynamic values
• Handle zero case in pluralization
• Group keys by feature module
• Use Locale enum for type safety
• Set Carbon locale in middleware

DON'T

• Concatenate translated strings
• Hardcode text in views
• Accept any locale without validation
• Create DB-based translations (use files)

---

Laravel 13 Notes

The localization API (__(), trans_choice(), App::setLocale()) is unchanged in Laravel 13. Specific points:

• Context::add('locale', $locale) propagates the locale into queued jobs (fixes the L12 bug where the locale was lost in ShouldQueue jobs)
• cache.serializable_classes (default false in L13): list your Locale objects if you cache them
• SetLocale middleware: compatible with the new PreventRequestForgery middleware from [[laravel-auth]]

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