I18N Routing Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — flag that immediately. If you're a Laravel dev, you cannot composer require it into a Laravel app and expect it to work; it hooks into Symfony's Kernel, RouteCollection, and DI container. If you're touching a legacy Symfony project (it's a 2013-era bundle with 3 stars and 0 dependents), start here:

1. Read the repo first, not the description. With this little usage, the README + the bundle's DependencyInjection and routing classes are the only reliable docs. Confirm the supported Symfony version in composer.json before anything else.
2. Install via composer require umpirsky/i18n-routing-bundle (accept the resolver prompt; expect it may pull an old Symfony constraint).
3. Register the bundle: Symfony 3/4 → AppKernel.php $bundles[] or config/bundles.php; older → app/AppKernel.php.
4. Confirm wiring: check that the bundle's compiler pass / route loader actually runs (bin/console debug:router), since a silent no-op is the most likely failure mode with a bundle this old.

First use case: locale-prefixed URLs generated from a single route definition — e.g. one contact route that resolves to /en/contact, /fr/contact, etc., without duplicating route entries. Verify this with debug:router before building on it.

Implementation Patterns

• Single definition, many locales. The bundle's stated value is "minimal performance cost" internationalized routing — i.e. it decorates or loads the route collection so you define a route once and it fans out per locale, rather than hand-writing a route per language. Keep route definitions in one routing.yml/controller annotation block and let the bundle/DI handle the locale dimension.
• Locale as a route parameter. Standard i18n routing uses {_locale} (Symfony's convention) in the path. Generate links with $router->generate('route_name', ['_locale' => 'fr']). Make sure your locale requirement regex (en|fr|de) is set so the matcher stays fast.
• Pair with a LocaleListener. Symfony usually resolves _locale from the request via a kernel.request listener. Don't rely on the bundle alone to set the app locale — register/confirm a listener that calls $request->setLocale() from _locale, otherwise your translator will still serve the default language even though the URL is localized.
• URL generation in Twig. Use path('route', {_locale: app.request.locale}) so links stay in the current language; keep a helper/macro to avoid repeating the locale arg everywhere.
• Cache warmup in CI. After adding the bundle, run bin/console cache:clear and, for prod, cache:warmup — routing is compiled, so a stale cache after a config change is a common false alarm.
• Fallback strategy. Decide the fallback locale in config.yml (framework.default_locale) and keep it consistent with the bundle's locale requirement, or unmatched paths will 404 instead of falling back.

Gotchas and Tips

• Wrong framework for a Laravel dev. There is no service provider, no facade, no Artisan command. If you need localized routing in Laravel, use mcamara/laravel-localization or spatie/laravel-translatable + route groups — do not force this bundle in.
• Effectively unmaintained. 3 stars, 0 dependents means no ecosystem testing and likely no modern Symfony support. Pin Symfony versions in composer.json, and budget time to fork/patch rather than wait for upstream fixes.
• Silent failure is the default failure. If debug:router shows no locale prefixes, the bundle isn't loading — check bundle registration, the compiler pass priority, and that your routes aren't bypassing the loader.
• Route ordering matters. A catch-all/default locale route placed before localized ones will shadow them; put specific locale-prefixed routes first in the collection.
• _locale vs. app locale drift. A localized URL does not automatically localize your translations — the two are separate. Debug with $request->getLocale() vs $request->attributes->get('_locale') when translations "don't switch."
• Debugging routing — use bin/console debug:router --show-controllers and router:match /fr/... to see exactly which route wins; this is the fastest way to tell whether the bundle or your listener is misbehaving.
• Extension points: if the bundle's loader doesn't cover your case, subclass/replace its route loader via the service definition, or drop it and use {_locale} prefixes directly with Symfony — for most apps the manual approach costs nothing and avoids the dependency.