I18N Routing Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require blablacar/i18n-routing-bundle
   

   Add to bundles.php (Symfony 2.x):

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

2. Configuration: Edit config/packages/blablacar_i18n_routing.yaml (or app/config/config.yml in Symfony 2.x):

   blablacar_i18n_routing:
       locales: ['en', 'fr', 'es']  # Supported locales
       default_locale: 'en'         # Fallback locale
       prefix_locale: true          # Prefix routes with locale (e.g., `/fr/home`)
       optional_locale: false       # Allow routes without locale (e.g., `/home`)
   

3. First Use Case: Define a locale-aware route in config/routes.yaml (Symfony 3.4+) or app/config/routing.yml (Symfony 2.x):

   home:
       path:     /{_locale}/home
       defaults: { _controller: 'App\Controller\HomeController::index' }
       requirements:
           _locale: %blablacar_i18n_routing.locales%
   

   Access via /en/home, /fr/home, etc. The bundle auto-detects locale from URL or session.

Implementation Patterns

Core Workflows

1. Locale Detection:

   • URL Prefix: /{locale}/path (e.g., /fr/products).
   • Subdomain: Configure via blablacar_i18n_routing.subdomain_locale: true (e.g., fr.example.com).
   • Session/Fallback: Defaults to default_locale if no locale is detected.

2. Route Generation: Use Symfony’s path() helper with _locale parameter:

   $url = $this->generateUrl('home', ['_locale' => 'fr']);
   // Output: /fr/home
   

3. Controller Integration: Access current locale in controllers:

   use Blablacar\I18nRoutingBundle\Locale\LocaleDetectorInterface;
   
   public function index(LocaleDetectorInterface $localeDetector)
   {
       $locale = $localeDetector->getLocale(); // 'fr', 'en', etc.
   }
   

4. Translation Integration: Combine with Symfony’s translator:

   $this->get('translator')->trans('welcome', [], null, $locale);
   

Advanced Patterns

• Dynamic Locale Switching:

  // In a controller
  $request->setLocale('es'); // Override for current request
  

• Locale-Aware Redirects:

  return $this->redirect($this->generateUrl('home', ['_locale' => $request->getLocale()]));
  

• Middleware for Locale Persistence: Store locale in session after detection (extend LocaleDetector):

  $session->set('_locale', $locale);
  

Gotchas and Tips

Pitfalls

1. Route Caching: Clear cache after changing locales or default_locale:

   php bin/console cache:clear
   

   Symfony 2.x: php app/console cache:clear.

2. Locale Requirements: Forgetting _locale in route requirements causes 404s. Always validate:

   requirements:
       _locale: %blablacar_i18n_routing.locales%|null  # Allow optional locales
   

3. Subdomain Conflicts: If using subdomains, ensure DNS and web server (Nginx/Apache) routes traffic correctly to Symfony. Test with:

   curl -H "Host: fr.example.com" http://localhost
   

4. Deprecated Symfony 2.x: The bundle is unmaintained for Symfony 3.4+. For newer projects, consider:

   • symfony/i18n (core component).
   • stof/doctrine-extensions for locale-aware entities.

Debugging Tips

• Check Detected Locale:

  dump($localeDetector->getLocale()); // Debug current locale
  

• Log Locale Switches:

  # config/packages/monolog.yaml
  handlers:
      i18n:
          type: stream
          path: "%kernel.logs_dir%/i18n.log"
          channels: ["i18n"]
  

  Log locale changes in a custom LocaleDetector:

  $this->get('logger')->info('Locale switched to', ['locale' => $locale]);
  

Extension Points

1. Custom Locale Detectors: Implement Blablacar\I18nRoutingBundle\Locale\LocaleDetectorInterface:

   class CustomDetector implements LocaleDetectorInterface
   {
       public function getLocale(Request $request)
       {
           // Custom logic (e.g., API header, cookie)
           return 'custom_locale';
       }
   }
   

   Register as service:

   services:
       app.locale_detector:
           class: App\Detector\CustomDetector
           tags: [{ name: 'blablacar_i18n_routing.locale_detector' }]
   

2. Override Route Generation: Extend the Router service to modify URL generation:

   $router->getContext()->setParameter('locale', $customLocale);
   

3. Locale-Specific Assets: Use Twig’s asset with locale:

   <link rel="stylesheet" href="{{ asset('css/style.' ~ app.locale ~ '.css') }}">