Laravel Multilingual Routes Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chinleung/laravel-multilingual-routes
   

2. Add Middleware (in bootstrap/app.php):

   $middleware->web(prepend: [DetectRequestLocale::class]);
   

3. Configure Locales:

   • Publish config:

     php artisan vendor:publish --provider="ChinLeung\MultilingualRoutes\MultilingualRoutesServiceProvider" --tag="config"
     

   • Set app.locales in .env or config/app.php (e.g., en,fr,es).

4. First Route:

   // routes/web.php
   Route::multilingual('home', 'HomeController')->name('home');
   

   • Generates /home (en), /fr/accueil (fr), etc. (requires resources/lang/fr/routes.php).

First Use Case: Localized View Route

Route::multilingual('about')->view('about');

• Renders resources/views/about.blade.php for all locales.
• URL: /about (en), /fr/a-propos (fr).

Implementation Patterns

Core Workflow

1. Route Registration:

   Route::multilingual('{resource}', 'Controller')->name('prefix');
   

   • Automatically generates routes for all configured locales.
   • Uses resources/lang/{locale}/routes.php for URI translations.

2. Resource Routes:

   Route::multilingualResource('posts', 'PostController');
   

   • Generates index, store, show, etc., for each locale.
   • Requires translations for all segments (e.g., posts/{post} → articles/{article}).

3. Locale-Specific Logic:

   Route::multilingual('contact')->only(['en', 'fr']); // Exclude other locales
   Route::multilingual('support')->except(['es']);     // Exclude Spanish
   

Integration Tips

1. Middleware:

   Route::multilingual('admin', 'AdminController')->middleware('auth');
   

   • Apply middleware to all locale variants.

2. Dynamic Names:

   Route::multilingual('blog')->names([
       'en' => 'blog',
       'fr' => 'journal',
   ]);
   

3. View Data:

   Route::multilingual('profile')->view('profile', ['user' => auth()->user()]);
   

4. Redirects:

   Route::multilingual('old-page')->redirect('new-page');
   

5. Signed Routes:

   URL::signedLocalizedRoute('unsubscribe', ['user' => 1]);
   

Advanced Patterns

1. Locale-Aware Controllers:

   public function __invoke(Request $request) {
       $locale = app()->getLocale();
       // Logic based on locale
   }
   

2. Fallback Routes:

   current_route('fr', route('fallback')); // Fallback if route doesn’t exist in FR
   

3. Route Caching:

   php artisan route:cache
   

   • Cache includes all locale variants.

4. API Routes:

   Route::prefix('api')->group(function () {
       Route::multilingual('v1/data', 'DataController');
   });
   

   • Prefix applies to all locale routes.

Gotchas and Tips

Pitfalls

1. Missing Translations:

   • Error: Route [fr.test] not defined.
   • Fix: Ensure resources/lang/fr/routes.php includes all route keys (e.g., test/{test} for resources).

2. Locale Detection Conflicts:

   • Issue: DetectRequestLocale may override app-wide locale.
   • Fix: Use app()->setLocale($locale) in middleware if needed.

3. Route Caching:

   • Issue: Changes to routes require route:clear or route:cache.
   • Fix: Avoid caching in development.

4. Default Locale Prefix:

   • Issue: Default locale (e.g., en) may not be prefixed (e.g., /home vs /fr/accueil).
   • Fix: Publish config and set prefix_default_locale: true.

5. Resource Route Parameters:

   • Issue: {resource} in URIs must match translation keys exactly.
   • Fix: Translate all segments (e.g., posts/{post} → publicaciones/{publicacion}).

Debugging Tips

1. List All Routes:

   php artisan route:list
   

   • Filter by locale (e.g., grep "fr\.").

2. Check Current Route:

   dd(current_route()); // Current locale
   dd(current_route('fr')); // French version
   

3. Test Locale Switching:

   app()->setLocale('fr');
   Route::getCurrentRoute()->uri; // Should reflect FR translation
   

4. Middleware Order:

   • Ensure DetectRequestLocale is first in the web group.

Extension Points

1. Custom URI Generator:

   • Override ChinLeung\MultilingualRoutes\RouteGenerator in a service provider.

2. Dynamic Locale Detection:

   • Extend DetectRequestLocale to support subdomains or query params:

     public function handle(Request $request, Closure $next) {
         $locale = $request->segment(1) ?? app()->getLocale();
         app()->setLocale($locale);
         return $next($request);
     }
     

3. Locale-Specific Middleware:

   Route::multilingual('admin')->middleware(['locale' => 'auth:admin']);
   

   • Use middleware with locale-specific logic.

4. Fluent API:

   • Chain methods like Laravel’s resource routes:

     Route::multilingualResource('users')
         ->only(['index', 'show'])
         ->middleware('auth')
         ->names(['en' => 'users', 'fr' => 'utilisateurs']);
     

Performance Tips

1. Avoid Dynamic Locale Switching:

   • Cache locale detection logic if possible.

2. Use localized_route():

   • Faster than route() + manual locale handling.

3. Minimize Translations:

   • Only translate necessary route segments.

4. Disable Caching in Dev:

   $this->app->routeMiddlewareGroup('web', [
       // ... other middleware
   ]);
   

   • Skip route:cache in config/caching.php.