Laravel Internationalization

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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