Laravel Internationalization
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Check existing translation patterns
- fuse-ai-pilot:research-expert - Verify Laravel i18n best practices via Context7
- 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
- Never concatenate strings - Use
:placeholder replacements
- Always handle zero in pluralization
- Group by feature -
auth.login.title, auth.login.button
- Extract strings early - No hardcoded text in views
- 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('fr');
App::currentLocale(); // 'fr'
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
L'API de localisation (__(), trans_choice(), App::setLocale()) reste inchangée en Laravel 13. Points spécifiques :
Context::add('locale', $locale) propage la locale dans les jobs queue (résout le bug L12 où la locale était perdue dans les ShouldQueue)
serializable_classes : whitelister vos Locale enums si utilisés en queue
- Middleware
SetLocale : compatible avec le nouveau validateOrigin() de [[laravel-auth]]
// app/Jobs/SendNotification.php
public function handle(): void
{
App::setLocale(Context::get('locale', 'en'));
Notification::send($this->user, new OrderShipped());
}
1---2name: laravel-i18n3description: Use when implementing Laravel translations — __(), trans_choice(), lang files, pluralization, locale middleware, or formatting.4versions:5 laravel: "13.0"6 php: "8.3"7user-invocable: true8references: references/localization.md, references/pluralization.md, references/blade-translations.md, references/middleware.md, references/formatting.md, references/packages.md, references/best-practices.md, references/templates/SetLocaleMiddleware.php.md, references/templates/lang-files.md, references/templates/LocaleServiceProvider.php.md, references/templates/LocaleRoutes.php.md9related-skills: laravel-blade, laravel-api10metadata:11 source: https://skillmd.com/skills/fusengine/laravel-i18n12---1314<objective>15Covers Laravel localization: PHP vs JSON translation files, pluralization16rules, Blade translation helpers, locale-detection middleware, date/number/17currency formatting, vendor package translations, and organizing18translations for large apps. Includes queue-safe locale propagation via19Context::add() in Laravel 13.20</objective>2122# Laravel Internationalization2324## Agent Workflow (MANDATORY)2526Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:27281. **fuse-ai-pilot:explore-codebase** - Check existing translation patterns292. **fuse-ai-pilot:research-expert** - Verify Laravel i18n best practices via Context7303. **mcp__context7__query-docs** - Check Laravel localization documentation3132After implementation, run **fuse-ai-pilot:sniper** for validation.3334---3536## Overview3738| Feature | PHP Files | JSON Files |39|---------|-----------|------------|40| Keys | Short (`messages.welcome`) | Full text |41| Nesting | Supported | Flat only |42| Best for | Structured translations | Large apps |4344---4546## Critical Rules47481. **Never concatenate strings** - Use `:placeholder` replacements492. **Always handle zero** in pluralization503. **Group by feature** - `auth.login.title`, `auth.login.button`514. **Extract strings early** - No hardcoded text in views525. **Validate locales** - Use enum or whitelist5354---5556## Decision Guide5758```59Translation task?60├── Basic string → __('key')61├── With variables → __('key', ['name' => $value])62├── Pluralization → trans_choice('key', $count)63├── In Blade → @lang('key') or {{ __('key') }}64├── Locale detection → Middleware65├── Format date/money → LocalizationService66└── Package strings → trans('package::key')67```6869---7071## Reference Guide7273### Concepts (WHY & Architecture)7475| Topic | Reference | When to Consult |76|-------|-----------|-----------------|77| **Setup** | [localization.md](references/localization.md) | Initial configuration |78| **Pluralization** | [pluralization.md](references/pluralization.md) | Count-based translations |79| **Blade** | [blade-translations.md](references/blade-translations.md) | View translations |80| **Middleware** | [middleware.md](references/middleware.md) | Locale detection |81| **Formatting** | [formatting.md](references/formatting.md) | Date/number/currency |82| **Packages** | [packages.md](references/packages.md) | Vendor translations |83| **Best Practices** | [best-practices.md](references/best-practices.md) | Large app organization |8485### Templates (Complete Code)8687| Template | When to Use |88|----------|-------------|89| [SetLocaleMiddleware.php.md](references/templates/SetLocaleMiddleware.php.md) | URL/session locale detection |90| [lang-files.md](references/templates/lang-files.md) | Translation file examples |91| [LocaleServiceProvider.php.md](references/templates/LocaleServiceProvider.php.md) | Centralized localization service |92| [LocaleRoutes.php.md](references/templates/LocaleRoutes.php.md) | URL prefix locale routing |9394---9596## Quick Reference9798```php99// Basic translation100__('messages.welcome')101102// With replacement103__('Hello :name', ['name' => 'John'])104105// Pluralization106trans_choice('messages.items', $count)107108// Runtime locale109App::setLocale('fr');110App::currentLocale(); // 'fr'111```112113---114115## Best Practices116117### DO118- Use `:placeholder` for dynamic values119- Handle zero case in pluralization120- Group keys by feature module121- Use Locale enum for type safety122- Set Carbon locale in middleware123124### DON'T125- Concatenate translated strings126- Hardcode text in views127- Accept any locale without validation128- Create DB-based translations (use files)129130---131132## Laravel 13 Notes133134L'API de localisation (`__()`, `trans_choice()`, `App::setLocale()`) reste **inchangée en Laravel 13**. Points spécifiques :135136- `Context::add('locale', $locale)` propage la locale dans les jobs queue (résout le bug L12 où la locale était perdue dans les ShouldQueue)137- `serializable_classes` : whitelister vos `Locale` enums si utilisés en queue138- Middleware `SetLocale` : compatible avec le nouveau `validateOrigin()` de [[laravel-auth]]139140```php141// app/Jobs/SendNotification.php142public function handle(): void143{144 App::setLocale(Context::get('locale', 'en'));145 Notification::send($this->user, new OrderShipped());146}147```