Localized Routes Plus Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require larasofthu/localized-routes-plus
   

   Publish the config:

   php artisan vendor:publish --provider="LarasoftHU\LocalizedRoutesPlus\LocalizedRoutesServiceProvider" --tag="config"
   

2. Configure Locales: Edit config/localized-routes-plus.php to define supported locales (e.g., ['en', 'hu']) and their routing strategies (prefix/subdomain).

3. First Use Case: Define a localized route in routes/web.php:

   Route::localized('home', function () {
       return view('welcome');
   })->middleware('web');
   

   This generates routes for all configured locales (e.g., /en/home, /hu/home or en.example.com/home).

Where to Look First

• Config File: config/localized-routes-plus.php (defines locales, strategies, and defaults).
• Route Macros: The package adds localized() to Laravel’s Route facade for fluent syntax.
• Middleware: Automatically binds App middleware to handle locale detection (e.g., from subdomains or URL prefixes).

Implementation Patterns

Core Workflows

1. Locale-Agnostic Route Definitions: Use Route::localized() to define routes once, letting the package generate locale-specific variants:

   Route::localized('products/{category}', 'ProductController@index')
        ->name('products.index');
   

   Generates:

   • /en/products/electronics (prefix strategy)
   • hu.example.com/products/electronics (subdomain strategy)

2. Dynamic Locale Detection: Leverage middleware to auto-detect locales from:

   • Subdomains: Configure subdomain_locales in the config (e.g., ['en' => 'en', 'hu' => 'hu']).
   • URL Prefixes: Configure prefix_locales (e.g., ['en' => 'en', 'hu' => 'hu']).
   • Query Parameters: Fallback to ?locale=hu if other methods fail.

3. Country-Specific Routing: Extend locales with country codes (e.g., en-us, hu-hu) in the config:

   'locales' => [
       'en-us', 'en-ca', 'hu-hu'
   ],
   

   Routes like /en-us/home are auto-generated.

4. Middleware Integration: Use the package’s middleware (Localize) in your app/Http/Kernel.php:

   protected $middlewareGroups = [
       'web' => [
           // ...
           \LarasoftHU\LocalizedRoutesPlus\Http\Middleware\Localize::class,
       ],
   ];
   

   This sets the app()->currentLocale dynamically based on the request.

Advanced Patterns

1. Locale-Specific Controllers: Override controller logic per locale by checking app()->getLocale():

   public function index()
   {
       if (app()->getLocale() === 'hu') {
           return view('hu.welcome');
       }
       return view('welcome');
   }
   

2. Fallback Locales: Configure a fallback locale in the config (e.g., default_locale = 'en') to handle unsupported locales gracefully.

3. Custom Route Generation: Extend the package’s route generator by publishing and modifying the RouteGenerator class:

   php artisan vendor:publish --provider="LarasoftHU\LocalizedRoutesPlus\LocalizedRoutesServiceProvider" --tag="routes"
   

4. API Localization: Use the same localized() macro for API routes in routes/api.php:

   Route::localized('api/v1/users', 'UserController@index');
   

   Ensures consistency between web and API routes.

Gotchas and Tips

Common Pitfalls

1. Locale Detection Order: The package checks subdomains → URL prefixes → query params → fallback. Override this in config/localized-routes-plus.php with locale_detection_order.

2. Subdomain Conflicts: Ensure your DNS supports subdomain routing (e.g., *.example.com). Wildcard subdomains may require server config (e.g., Nginx/Apache).

3. Route Caching: Clear route cache after changing locales or strategies:

   php artisan route:clear
   

4. Middleware Collisions: If using other localization packages (e.g., laravel-localization), disable their middleware to avoid conflicts.

Debugging Tips

1. Check Current Locale: Add this to a route to debug:

   Route::get('/debug-locale', function () {
       return "Current locale: " . app()->getLocale();
   });
   

2. Route Listing: Use php artisan route:list to verify generated routes. Filter by locale-specific paths (e.g., grep "hu/").

3. Log Locale Detection: Temporarily add logging to the Localize middleware:

   public function handle($request, Closure $next)
   {
       \Log::info('Detected locale:', ['locale' => $request->locale]);
       return $next($request);
   }
   

Extension Points

1. Custom Locale Providers: Implement LarasoftHU\LocalizedRoutesPlus\Contracts\LocaleProvider to add new detection logic (e.g., cookies or headers).

2. Route Naming: Override the default naming convention by extending the RouteGenerator:

   public function generateLocalizedRouteName($name, $locale)
   {
       return "{$locale}.{$name}";
   }
   

3. Locale-Specific Assets: Use the localized-asset helper (if included) or middleware to serve locale-specific JS/CSS:

   // In a blade template
   <link href="{{ localized_asset('css/app.hu.css') }}" rel="stylesheet">
   

4. Testing: Mock locale detection in tests:

   $request = new Request(['locale' => 'hu']);
   $response = $this->actingAs($user)->withHeaders(['X-Locale' => 'hu'])->get('/');