Getting Started

Install the package via Composer:

composer require laravel-lang/routes

Publish the configuration (if needed) to customize middleware or locale detection logic:

php artisan vendor:publish --provider="LaravelLang\Routes\RoutesServiceProvider"

First Use Case: Localize a route group by language prefix (e.g., /en/about, /fr/about):

use LaravelLang\Routes\Route;

Route::localizedGroup(['prefix' => 'locale'], function () {
    Route::get('/about', [AboutController::class, 'index']);
});

Verify the route works by accessing http://your-app.test/en/about and http://your-app.test/fr/about.

Implementation Patterns

1. Route Localization via Prefix

Use localizedGroup() to prefix routes with the current locale:

Route::localizedGroup(['prefix' => 'locale'], function () {
    Route::get('/contact', [ContactController::class, 'show']);
});

Dynamic Prefix: The locale prefix will auto-resolve based on the detected language (e.g., en, fr).

2. Locale Detection Strategies

The package supports multiple middleware for locale detection:

Header-Based: Detect locale from Accept-Language header.

Route::localizedGroup(['middleware' => 'localization-by-header'], function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

Session-Based: Store locale in the user’s session.

Route::localizedGroup(['middleware' => 'localization-by-session'], function () {
    Route::get('/profile', [ProfileController::class, 'edit']);
});

Model-Based: Fetch locale from a user/model attribute.

Route::localizedGroup(['middleware' => 'localization-by-model:User'], function () {
    Route::get('/settings', [SettingsController::class, 'show']);
});

3. URL Generation

Generate localized URLs using the localizedRoute() helper:

$url = localizedRoute('contact.show', ['locale' => 'es']); // /es/contact

Or omit the locale to use the current app locale:

$url = localizedRoute('contact.show'); // /en/contact (if app locale is 'en')

4. Route Grouping Without Prefix

For APIs or non-prefix routes, use localizedGroup with prefix: '':

Route::localizedGroup(['prefix' => ''], function () {
    Route::apiResource('posts', PostController::class);
});

Access via /posts with the locale resolved via middleware (e.g., header/session).

5. Middleware Configuration

Customize middleware in config/routes.php:

'middleware' => [
    'localization-by-header' => \LaravelLang\Routes\Middleware\LocalizationByHeader::class,
    'localization-by-session' => \LaravelLang\Routes\Middleware\LocalizationBySession::class,
    'localization-by-model' => \LaravelLang\Routes\Middleware\LocalizationByModel::class,
],

6. Event Listeners

Listen for LocaleHasBeenSetEvent to react to locale changes:

use LaravelLang\Routes\Events\LocaleHasBeenSet;

public function boot()
{
    event(LocaleHasBeenSet::class, function (LocaleHasBeenSet $event) {
        // Log or trigger side effects when locale changes
    });
}

Gotchas and Tips

Pitfalls

Locale Not Detected:
- Ensure middleware is correctly configured in App\Http\Kernel::$middlewareGroups.
- For LocalizationByModel, verify the model’s locale attribute exists (e.g., user->locale).
URL Generation Issues:
- If localizedRoute() returns unexpected URLs, check the app.locale config or override it in the route call:
```
localizedRoute('route.name', ['locale' => 'de']);
```
Session Middleware Without Session:
- The LocalizationBySession middleware will fail if the session driver is not configured. Use localization-by-header as a fallback.
Route Caching Conflicts:
- Clear route cache (php artisan route:clear) after adding/removing localized routes:
```
php artisan route:clear
```

Middleware Order Matters:

Place locale detection middleware before StartSession or Authenticate to ensure the locale is resolved early:

protected $middlewareGroups = [
    'web' => [
        \LaravelLang\Routes\Middleware\LocalizationByHeader::class,
        // Other middleware...
    ],
];

Debugging Tips

Check Detected Locale: Add a temporary middleware to log the resolved locale:

public function handle($request, Closure $next)
{
    \Log::info('Current locale:', ['locale' => app()->getLocale()]);
    return $next($request);
}

Validate Route Binding: Use php artisan route:list to verify localized routes:
```
php artisan route:list | grep "locale"
```
Test Locale Switching: Manually set headers or session data to test different locales:
```
curl -H "Accept-Language: fr" http://your-app.test/about
```

Extension Points

Custom Middleware: Extend LocalizationByHeader or LocalizationByModel for custom logic:

namespace App\Http\Middleware;

use LaravelLang\Routes\Middleware\LocalizationByHeader;

class CustomLocalizationByHeader extends LocalizationByHeader
{
    protected function getLocaleFromHeader($request)
    {
        // Custom logic (e.g., prioritize query param)
        return $request->query('lang', parent::getLocaleFromHeader($request));
    }
}

Override Locale Resolution: Bind a custom resolver to the container:

$this->app->bind(\LaravelLang\Routes\Contracts\LocaleResolver::class, function () {
    return new \App\Services\CustomLocaleResolver();
});

Add Locale to Redirects: Extend the Redirector to preserve locale in redirects:

use Illuminate\Routing\Redirector;

class CustomRedirector extends Redirector
{
    public function toRoute($route, $parameters = [], $status = 302)
    {
        $parameters['locale'] = app()->getLocale();
        return parent::toRoute($route, $parameters, $status);
    }
}

Performance Quirks

Avoid Overhead in APIs: For API routes, use localizedGroup with prefix: '' and disable unnecessary middleware (e.g., session-based localization).

Cache Locale Resolution: If using a database-backed locale resolver, cache the result:

$locale = Cache::remember("user_{$user->id}_locale", now()->addHours(1), function () use ($user) {
    return $user->locale;
});

Laravel 13-Specific Notes

New Blade Features: If using Blade’s new {{ }} syntax, ensure no conflicts with the package’s route helpers.
Dependency Injection: Laravel 13’s stricter type hints may require updating the package’s type declarations (check for array vs array<string, mixed>).

Routes Laravel Package