/laravel-i18n

name: laravel-i18n
description: Use when implementing Laravel translations — __(), trans_choice(), lang files, pluralization, locale middleware, or formatting.
versions:
  laravel: "13.0"
  php: "8.3"
user-invocable: true
references: 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.md
related-skills: laravel-blade, laravel-api

<objective> 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. </objective>

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](references/localization.md) | Initial configuration | | **Pluralization** | [pluralization.md](references/pluralization.md) | Count-based translations | | **Blade** | [blade-translations.md](references/blade-translations.md) | View translations | | **Middleware** | [middleware.md](references/middleware.md) | Locale detection | | **Formatting** | [formatting.md](references/formatting.md) | Date/number/currency | | **Packages** | [packages.md](references/packages.md) | Vendor translations | | **Best Practices** | [best-practices.md](references/best-practices.md) | Large app organization |

Templates (Complete Code)

| Template | When to Use | |----------|-------------| | [SetLocaleMiddleware.php.md](references/templates/SetLocaleMiddleware.php.md) | URL/session locale detection | | [lang-files.md](references/templates/lang-files.md) | Translation file examples | | [LocaleServiceProvider.php.md](references/templates/LocaleServiceProvider.php.md) | Centralized localization service | | [LocaleRoutes.php.md](references/templates/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());
}