I18N Routing Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require audioteka/i18n-routing-bundle
   

   Register the bundle in config/bundles.php:

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

2. Configure Locales Update config/packages/audioteka_jms_i18n_routing.yaml (or create it):

   jms_i18n_routing:
       default_locale: en
       locales: [en, fr, es]
       strategy: prefix_except_default
   

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

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

   Access routes via:

   $router->generate('app_homepage', ['_locale' => 'fr']);
   

Implementation Patterns

Core Workflows

1. Locale-Aware Routing

   • Use _locale as a route parameter (e.g., /{_locale}/products).
   • Leverage strategy (prefix, suffix, domain, or custom) to handle locale placement.
   • Example: Prefix strategy (/en/home, /fr/accueil).

2. Dynamic Locale Detection

   • Integrate with Request to auto-detect locale from:
     • URL (e.g., /fr/...).
     • Subdomain (e.g., fr.example.com).
     • Header (Accept-Language).
   • Use JMSI18nRoutingBundle\Routing\Router to generate locale-aware URLs.

3. Translation in Controllers

   • Inject TranslatorInterface to fetch translated content:

     public function index(TranslatorInterface $translator)
     {
         return $this->render('home/index.html.twig', [
             'title' => $translator->trans('home.title'),
         ]);
     }
     

4. Route Collections

   • Group locale-specific routes in YAML:

     app_locales:
         resource: '@AppBundle/Resources/config/routing/locales.yaml'
         type: jms_i18n_routing
     

Integration Tips

• Symfony 5+ Compatibility: Use symfony/routing v5+ with require-dev constraints.
• Twig Integration: Extend JMSI18nRoutingBundle\Twig\RoutingExtension for locale-aware path() in templates.
• APIs: Combine with NelmioApiDocBundle for multilingual API docs by overriding _locale in route annotations.

Gotchas and Tips

Pitfalls

1. Locale Parameter Conflicts

   • Avoid naming route parameters _locale if they clash with existing parameters.
   • Fix: Use _lang or rename in requirements.

2. Caching Issues

   • Clear cache after changing locales or strategy:

     php bin/console cache:clear
     

3. Symfony 2.1 Legacy

   • The bundle targets Symfony 2.1+. For newer versions, expect deprecation warnings.
   • Workaround: Override Router class to adapt to Symfony 4/5 routing.

4. Domain Strategy Quirks

   • Domain-based routing (e.g., fr.example.com) requires DNS/subdomain setup.
   • Tip: Use jms_i18n_routing.domain config to map locales to subdomains.

Debugging

• Route Dumping: Use php bin/console debug:router to inspect locale-aware routes.
• Locale Resolution: Log the resolved locale in a controller:

  public function index(Request $request)
  {
      $locale = $request->get('_locale', $this->container->getParameter('locale'));
      // ...
  }
  

Extension Points

1. Custom Strategies

   • Extend JMSI18nRoutingBundle\Routing\Strategy\StrategyInterface for unique locale handling (e.g., query params like ?lang=fr).

2. Event Listeners

   • Subscribe to jms_i18n_routing.locale_resolved to modify locale resolution dynamically.

3. Override Templates

   • Customize Twig extensions in config/packages/twig.yaml:

     twig:
         globals:
             jms_i18n_routing: '@jms_i18n_routing.twig.extension'
     

Pro Tips

• Fallback Locales: Configure fallback_locale to redirect unsupported locales to default_locale.
• Performance: Cache translated routes with jms_i18n_routing.cache_enabled: true.
• Testing: Use RouterInterface mocks in PHPUnit to test locale-aware routes:

  $router = $this->createMock(RouterInterface::class);
  $router->method('generate')->willReturn('/fr/test');