## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require niels-numbers/laravel-localizer

Publish the config (optional):

php artisan vendor:publish --provider="NielsNumbers\Localizer\LocalizerServiceProvider" --tag="config"

Configure Locales: Edit config/localizer.php to define supported locales (e.g., ['en', 'de', 'fr']) and set a default.

First Localized Route:

Route::localize(function () {
    Route::get('/about', [AboutController::class, 'index'])->name('about');
});

This generates:

/about (auto-detects locale)
/en/about, /de/about, etc. (explicit locales)

Detect User Locale: Override config/localizer.php's detectors array to use custom logic (e.g., user profile, cookie, or session).
Test the Flow:
- Visit /about → Redirects to /en/about (or your default locale).
- Visit /de/about → Stays on /de/about (explicit locale wins).

Implementation Patterns

Core Workflow: Localization in Action

Route Registration: Use Route::localize() as a wrapper for all public routes needing localization. Example:
```
Route::localize(function () {
    Route::get('/products/{product}', [ProductController::class, 'show'])->name('products.show');
});
```
- Generates /products/{product} (auto-detect) and /{locale}/products/{product}.
Locale Detection Chain: The package checks these signals in order:
- Explicit URL prefix (e.g., /de/about).
- Session cookie (localizer_locale).
- Accept-Language header (default detector).
- Fallback to config/localizer.default_locale.

Middleware Integration: Add to app/Http/Kernel.php:

protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \NielsNumbers\Localizer\Middleware\SetLocale::class,
        \NielsNumbers\Localizer\Middleware\RedirectLocale::class,
    ],
];

Order Matters: SetLocale must run after StartSession (to read session locale) and before SubstituteBindings (to resolve translated route models correctly).

Locale Switching:
- URL Switcher: Use route('about') in Blade (auto-localized).
- Language Links: Generate switcher URLs with:
```
{{ route('about', [], ['locale' => 'de']) }}
```
- JavaScript Helpers: For Ziggy/Inertia, bind the LocalizerBladeRouteGeneratorV2 (see docs).

Dynamic Locale Handling:

Override Locale Temporarily:

Localizer::setLocale('fr');
// ... logic using French locale
Localizer::forgetLocale(); // Reset to previous

Locale-Aware Redirects:

return redirect()->localized('products.show', ['product' => $id]);

Blade Directives:

Current Locale:

{{ Localizer::currentLocale() }}  <!-- e.g., 'de' -->

Localized URLs:

<a href="{{ route('about') }}">About</a>  <!-- Auto-localized -->

RTL/LTR Direction:

<html dir="{{ Localizer::currentLocaleDirection() }}">

API Routes:

Exclude from localization if needed:

Route::prefix('api')->group(function () {
    Route::middleware('api')->group(function () {
        Route::get('/products', [ProductController::class, 'index']);
    });
});

Integration Tips

Ziggy/Inertia:

Bind LocalizerBladeRouteGeneratorV2 in AppServiceProvider:

public function register()
{
    $this->app->bind(
        \Tighten\Ziggy\BladeRouteGenerator::class,
        \NielsNumbers\Localizer\Ziggy\LocalizerBladeRouteGeneratorV2::class
    );
}

For Inertia, ensure localizer_locale is shared in props.

Translated Route Bindings:
- Use {post:slug} in routes with Route::localize(). The SubstituteBindings middleware resolves the model in the correct locale.
Fallback Locales:
- Configure config/localizer.php:
```
'fallback_locales' => ['en'],
```
- Ensures unsupported locales (e.g., /es/about) fall back to en.
Caching:
- Routes are static and route:cache compatible. Run:
```
php artisan route:cache
```
- Clear cache when locales change:
```
php artisan route:clear
```

Testing:

Mock locale detection:

Localizer::shouldReceive('detectLocale')->andReturn('fr');

Test redirects:

$response = $this->get('/about');
$response->assertRedirect('/fr/about');

Gotchas and Tips

Pitfalls

Case-Sensitive Locale Prefixes:
- /EN/about (wrong case) will 404 unless you configure case-insensitive matching in Route::localize() (not supported by default; requires custom regex).
- Fix: Use lowercase in URLs or configure a custom detector to normalize case.

Middleware Order:

Symptom: Translated route bindings (e.g., {post:slug}) resolve to the wrong locale.
Cause: SetLocale runs after SubstituteBindings.

Fix: Reorder middleware in Kernel.php:

protected function middlewareGroup($group, array $middleware)
{
    // Remove existing middleware
    $middleware = collect($middleware)->reject(fn ($item) =>
        $item instanceof SetLocale || $item instanceof RedirectLocale
    )->toArray();

    // Append in correct order
    return array_merge($middleware, [
        SetLocale::class,
        RedirectLocale::class,
    ]);
}

Route Defaults Leak:
- Symptom: Route::localizedUrl() appends route defaults as query params (e.g., /about?view=home).
- Fix: Updated in v1.2.2; ensure you’re on the latest version.
Session Locale Persistence:
- Symptom: Locale resets on page refresh.
- Cause: Missing localizer_locale cookie or session driver.
- Fix: Ensure SESSION_DRIVER is file, database, or redis in .env.
Ziggy/TypeScript Issues:
- Symptom: route() helper fails in browser with "invalid regexp group".
- Cause: Ziggy v1 shipped PCRE-only regex flags (e.g., (?i)).
- Fix: Upgrade to LocalizerBladeRouteGeneratorV2 (v1.3.2+).
Default Locale Visibility:
- Symptom: /about (default locale) doesn’t show locale prefix even when hide_default_locale: false.
- Cause: RedirectLocale skips default locale by default.
- Fix: Set 'hide_default_locale' => false in config.
Route Name Confusion:
- Symptom: $route->getName() returns with_locale.about instead of about.
- Fix: Use Localizer::baseName($route->getName()) or the baseName() macro:
```
$route->baseName(); // Returns 'about'
```

Debugging Tips

Log Locale Detection: Add to AppServiceProvider:
```
Localizer::detectLocale(); // Log the result
```
Inspect Route Registration: Dump registered routes:
```
php artisan route:list | grep localizer
```
Look for with_locale.* and without_locale.* prefixes.
Disable Redirects Temporarily: Set 'redirect' => false in config to debug without redirects.
Check Middleware: Verify SetLocale and RedirectLocale are registered:
```
php artisan middleware:list
```

Test Locale Switcher: Manually set the locale cookie:

curl -H "Cookie: localizer_locale=fr" http://localhost/about

Laravel Localizer Laravel Package