I18N Routing Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require jms/i18n-routing-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       JMS\I18nRoutingBundle\JMSI18nRoutingBundle::class => ['all' => true],
   ];
   

2. Configure Locales: Edit config/packages/jms_i18n_routing.yaml:

   jms_i18n_routing:
       default_locale: en
       locales: [en, fr, de]
       routing:
           prefix_locale: true
           prefix_default_locale: false
   

3. First Use Case: Define a route with locale prefix in config/routes.yaml:

   app_home:
       path: /{_locale}/home
       defaults: { _controller: 'App\Controller\HomeController::index' }
       requirements:
           _locale: ^(en|fr|de)$
   

   Access via /en/home, /fr/home, etc.

Implementation Patterns

Route Definition Workflows

1. Locale Prefix Routing: Use {_locale} as a route parameter to enforce locale-based URLs. Example:

   app_blog_post:
       path: /{_locale}/blog/{slug}
       defaults: { _controller: 'App\Controller\BlogController::show' }
   

2. Dynamic Locale Switching: In controllers, access the current locale via:

   $locale = $this->get('request_stack')->getCurrentRequest()->get('_locale');
   

3. Locale-Aware Redirects: Use JMS\I18nRoutingBundle\Router\Router to generate locale-specific URLs:

   $router = $this->container->get('router');
   $url = $router->generate('app_home', ['_locale' => 'fr']);
   

Integration Tips

1. Symfony Forms: Bind locale to form fields for multi-lingual data:

   $form = $this->createFormBuilder()
       ->add('title', TextType::class, ['attr' => ['data-locale' => $locale]])
       ->getForm();
   

2. Twig Integration: Use path() with _locale in templates:

   <a href="{{ path('app_home', {'_locale': app.request.locale}) }}">Home</a>
   

3. APIs: For REST APIs, use _locale as a query parameter or header:

   api_home:
       path: /api/home
       defaults: { _controller: 'App\Controller\ApiController::home' }
       requirements:
           _locale: ^(en|fr|de)$
   

Gotchas and Tips

Common Pitfalls

1. Locale Parameter Conflicts: Avoid naming route parameters _locale if they conflict with the bundle’s reserved parameter. Use _lang instead:

   app_profile:
       path: /{_lang}/profile/{id}
       requirements:
           _lang: ^(en|fr)$
   

2. Default Locale Overrides: If prefix_default_locale: true, ensure your base routes (e.g., /) are explicitly defined to avoid 404s.

3. Caching Issues: Clear Symfony’s route cache after changing locales or routes:

   php bin/console cache:clear
   

Debugging Tips

1. Route Dumping: Use the debug command to inspect routes:

   php bin/console debug:router
   

   Filter by locale-specific routes with --format=json and grep for _locale.

2. Locale Detection: Override locale detection logic in config/packages/jms_i18n_routing.yaml:

   jms_i18n_routing:
       locale_mapper:
           default_locale: en
           locales: [en, fr]
           strategy: 'prefix'
           # Custom strategy example:
           # strategy: 'custom'
           # custom_strategy: 'App\Service\CustomLocaleStrategy'
   

3. Fallback Locales: Configure fallback locales to handle missing translations gracefully:

   jms_i18n_routing:
       fallback_locale: en
   

Extension Points

1. Custom Locale Strategies: Implement JMS\I18nRoutingBundle\Model\LocaleStrategyInterface for dynamic locale resolution (e.g., subdomains, cookies).

2. Route Loaders: Extend JMS\I18nRoutingBundle\Loader\RouterLoaderInterface to modify route generation for specific bundles.

3. Event Listeners: Subscribe to jms_i18n_routing.locale_changed events to trigger locale-specific logic:

   use JMS\I18nRoutingBundle\Event\LocaleEvent;
   
   public function onLocaleChanged(LocaleEvent $event) {
       // Custom logic (e.g., update session, headers)
   }