Agent Skills: Laravel Internationalization

Laravel Internationalization

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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('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());
}