L10N Bundle Laravel Package

Getting Started

First, calibrate expectations: lafourchette/l10n-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no facade, and no config/l10n.php. "Leveraging it day-to-day" therefore means one of two things:

1. You are working in a Symfony app (or a Symfony service inside a mixed stack) and can install it directly.
2. You are in Laravel and are evaluating it as a reference implementation for locale/country handling, not as a dependency.

Minimal evaluation steps (do these before committing to it):

composer require lafourchette/l10n-bundle

Then read, in this order:

• src/L10nBundle.php — the bundle class; tells you what it registers.
• src/DependencyInjection/Configuration.php — the actual config tree. This is the real documentation for a bundle with sparse READMEs.
• src/DependencyInjection/L10nExtension.php — shows which services are wired and under what IDs.
• Any EventListener/ or EventSubscriber/ directory — this is where locale detection/negotiation almost certainly lives.

Register it in config/bundles.php:

return [
    // ...
    Lafourchette\L10nBundle\L10nBundle::class => ['all' => true],
];

First use case to validate: locale persistence across a request. Configure the bundle to read a locale from the request (header, query string, or route parameter), then confirm a controller can read it back. If that round-trip doesn't work cleanly, stop — the rest of the bundle's value is built on top of it.

In Laravel specifically: do not install this. Instead read Configuration.php and the listeners, then reimplement the equivalent as a middleware + App::setLocale() + a route/session strategy. You'll get 90% of the behavior with 100% less integration friction.

Implementation Patterns

Locale negotiation at the edge. The bundle's core value is deciding "what locale is this request?" before your controllers run. In Symfony this is an event listener on kernel.request. The Laravel analogue is a middleware registered globally:

// app/Http/Middleware/SetLocale.php
public function handle($request, Closure $next)
{
    $locale = $request->session()->get('locale')
        ?? $this->negotiateFromHeader($request)
        ?? config('app.locale');

    app()->setLocale($locale);
    return $next($request);
}

Keep negotiation order explicit and documented. Precedence bugs here are the #1 source of "why is my site in French" tickets.

Country + language as a pair. Lafourchette's domain is restaurant booking across markets, so the bundle's model is typically (language, country) rather than a bare locale. If you copy the pattern, model it as two fields:

// config/l10n.php
return [
    'supported' => [
        'fr_FR' => ['language' => 'fr', 'country' => 'FR', 'currency' => 'EUR'],
        'en_GB' => ['language' => 'en', 'country' => 'GB', 'currency' => 'GBP'],
    ],
    'fallback_language' => 'en',
];

Resolve language for translations and country for currency/formatting separately. Collapsing them into one locale string works until a UK user wants to read in French.

URL-prefixed routing. The common integration is /{_locale}/... routes with a default. In Laravel:

Route::group(['prefix' => '{locale}', 'middleware' => 'setlocale'], function () {
    // ...
})->whereIn('locale', array_keys(config('l10n.supported')));

Generate links with the active locale explicitly rather than relying on a global helper — it makes locale leaks visible in code review.

Locale switcher as a first-class action. A POST /locale endpoint that validates against supported, writes to session, and redirects back to the same URL with the prefix swapped. Never trust a ?locale= query param to set the locale directly; it invites cache-poisoning and open-redirect issues.

Translation fallback chain. Configure fallback_locale to walk fr_CA → fr → en rather than jumping straight to en. In Laravel this is a custom FileLoader or a wrapper around __() that tries each candidate before falling back.

Gotchas and Tips

• The framework mismatch is the headline risk. Zero stars, zero dependents, and a Symfony bundle means no community answers when it breaks. Budget for reading source, not searching Stack Overflow.
• Sparse docs. For bundles like this, Configuration.php is the manual. Read the config tree first; the README will lag the code.
• Don't composer require this into a Laravel app. You'll pull Symfony contracts, event dispatcher expectations, and bundle bootstrapping that Laravel won't run. If you need the behavior, port it.
• Session vs. URL precedence. Decide once whether the URL prefix or the session value wins, and enforce it in a single place. Two sources of truth produce flickering locales.
• Cache keys must include locale. Any full-page or response cache that ignores the negotiated locale will serve French pages to English users. Vary on Accept-Language and the route prefix.
• Debugging tip: log the negotiated locale, the source it came from (session, header, route), and the final resolved translation locale. Three values, one log line. This turns most locale bugs into a one-minute diagnosis.
• Extension points to look for: a locale-negotiation strategy interface, a country/language resolver service, and Twig/Blade helpers. If the bundle exposes interfaces for these, wrap them; if it hardcodes logic in listeners, treat it as a spec to copy rather than a library to depend on.
• Maintenance check before adopting: commit recency on GitHub, whether it supports your Symfony version's contracts, and whether tests exist. A localization layer is infrastructure — you don't want to be its maintainer by accident.
• PHP version pin risk. Older Symfony bundles often cap PHP (^7.x) and will block composer update on modern stacks. Check composer.json constraints first.