Laravel Localizer Laravel Package

Technical Evaluation

Architecture Fit

• Enforced Route Naming for Translated Routes: The new Route::translate() now mandates named routes, aligning with Laravel’s best practices for route resolution and localization. This ensures consistency in locale switching (e.g., Route::localizedUrl()) and prevents runtime failures by failing fast at registration.
• Unnamed Route Handling: Routes inside Route::localize() without explicit names remain unnamed, mirroring Laravel’s default behavior. This avoids unintended name collisions (e.g., with_locale. prefix) and clarifies that such routes are URL-accessible but not locale-switchable.
• Middleware and Facade Consistency: The package’s core architecture (facade, middleware, route macros) remains unchanged, preserving seamless integration with Laravel’s routing and middleware systems.
• Locale-Aware URL Generation: The Route::localizedUrl() helper now has a guaranteed contract (all translated routes are named), improving reliability for client-side navigation (e.g., Ziggy/Inertia).

Integration Feasibility

• Strict Route Naming: Requires explicit ->name() for all routes inside Route::translate(), which may necessitate updates to existing route definitions. This is a breaking change but enforces better practices.
• Unnamed Route Clarity: Routes inside Route::localize() without names are now explicitly unnamed, reducing ambiguity in route resolution. This aligns with Laravel’s default behavior and avoids silent name collisions.
• JavaScript Route Helpers: The deprecation of spatie/laravel-typescript-transformer support (due to generator limitations) narrows frontend compatibility but clarifies that Ziggy remains the recommended solution for client-side locale-aware routing.
• Backward Compatibility: Existing Route::localize() usage without ->name() continues to work but with adjusted behavior (unnamed routes stay unnamed). This may require testing for apps relying on implicit naming.

Technical Risk

• Route Naming Enforcement: Apps with unnamed routes in Route::translate() will fail at boot, requiring proactive updates. This reduces runtime errors but increases migration effort.
• Unnamed Route Behavior: Routes inside Route::localize() without names are now truly unnamed (not auto-named), which may break apps expecting them to be resolvable by name. Test route('with_locale.')-style lookups.
• Ziggy Dependency: With spatie/laravel-typescript-transformer removed, Ziggy becomes the sole recommended JS adapter. Apps using the transformer will need to migrate to Ziggy or Wayfinder for static route generation.
• Middleware Interaction: No changes to middleware logic, but the stricter route naming may expose latent issues in locale resolution (e.g., missing RedirectLocale triggers).
• Route Caching: The package’s compatibility with route:cache remains intact, but cached routes must now adhere to the naming rules. Test cached route regeneration post-migration.

Key Questions

1. Route Naming Compliance:
   • Are there routes inside Route::translate() without explicit names? How many need updates?
   • Does the app rely on auto-generated names (e.g., with_locale.) for route resolution?
2. Unnamed Route Impact:
   • Are there Blade templates or JS code using route('with_locale.')-style lookups for unnamed routes?
   • Does the app use Route::has() or Route::named() checks that may now fail?
3. Frontend Integration:
   • Is spatie/laravel-typescript-transformer used for static route generation? If so, what’s the migration path to Ziggy/Wayfinder?
   • Are there custom route helpers or manifest generators that need updates?
4. Testing Strategy:
   • Should tests verify that all translated routes are named and resolvable via Route::localizedUrl()?
   • Are there edge cases for unnamed routes in Route::localize() (e.g., fallback routes)?
5. Middleware Validation:
   • Does the app use custom middleware that might conflict with the new naming enforcement (e.g., route filtering)?
6. Performance:
   • Could the stricter naming rules affect route caching or compilation speed?
7. Deprecation Timeline:
   • What’s the timeline for spatie/laravel-typescript-transformer support removal (if any)? Are there alternatives like Wayfinder?

Integration Approach

Stack Fit

• Laravel Versions: Continues to support Laravel 9–13 with PHP 8.2–8.4. No changes to core compatibility.
• Frontend Frameworks:
  • Ziggy/Inertia: Remains the primary JS adapter. Ziggy v2 support is preserved via LocalizerBladeRouteGeneratorV2.
  • Livewire: Unaffected; continues to work with Ziggy integration.
  • Static Site Generators: Wayfinder is now the recommended alternative to spatie/laravel-typescript-transformer. Wayfinder uses route names (not controller methods), making it compatible with Route::localize().
• Middleware: No changes to middleware architecture. The SetLocale/RedirectLocale pipeline remains unchanged.
• Route Caching: Fully compatible with route:cache. Cached routes must now adhere to naming rules.

Migration Path

1. Update Route Definitions:
   • Add explicit ->name() to all routes inside Route::translate():

     Route::translate(function () {
         Route::get('/about', [AboutController::class, 'index'])->name('about'); // Now required
         Route::get('/contact', [ContactController::class, 'index'])->name('contact');
     });
     

   • For Route::localize(), unnamed routes will no longer auto-generate names. Update references to route('with_locale.') if used.
2. Frontend Migration:
   • Replace spatie/laravel-typescript-transformer with Wayfinder for static route generation:

     composer require wayfinderjs/wayfinder
     

     Configure Wayfinder to use route names (not controller methods) in wayfinder.php:

     'route_resolver' => \Wayfinder\RouteResolver::class,
     'route_name_resolver' => \Wayfinder\RouteNameResolver::class, // Use names, not controllers
     

   • Rebuild assets after updating JS route helpers.
3. Testing:
   • Verify all translated routes are named and resolvable via Route::localizedUrl().
   • Test unnamed routes in Route::localize() to ensure they remain URL-accessible but not locale-switchable.
4. Middleware Validation:
   • Confirm SetLocale and RedirectLocale are correctly ordered in app/Http/Kernel.php.
5. Route Caching:
   • Regenerate cached routes (php artisan route:cache) after updates.

Compatibility

• Route Naming: Enforced for Route::translate(); optional (but discouraged) for Route::localize().
• Ziggy/Inertia: Fully compatible. Ziggy v2 requires the LocalizerBladeRouteGeneratorV2 binding.
• Wayfinder: Now the recommended static route generator (replaces spatie/laravel-typescript-transformer).
• Blade Directives: @route and @routes work with named routes. Unnamed routes in Route::localize() are not resolvable by name.
• Query Strings: Preserved during locale switches (no changes from v1.2.2).

Sequencing

1. Route Updates:
   • Prioritize Route::translate() routes for naming updates.
   • Audit Route::localize() for unnamed routes and update references.
2. Frontend Migration:
   • Replace spatie/laravel-typescript-transformer with Wayfinder before updating route helpers.
3. Testing:
   • Test locale redirects, URL generation, and middleware interactions before deploying to production.
4. Deployment:
   • Regenerate route cache (route:cache) post-migration.

Operational Impact

Maintenance

• Configuration:
  • No changes to core config. Custom detectors or RTL rules remain configurable via localizer.detectors and localizer.locale_directions.
  • Wayfinder config may need adjustments for route name resolution.
• Updates:
  • Minor updates are backward-compatible. Breaking changes (e.g., route naming) are documented in the changelog.
  • Monitor for future Ziggy/Wayfinder compatibility updates.
• Debugging:
  • New UnnamedTranslatedRouteException provides clear error messages for missing route names.
  • Facade methods (Localizer::currentLocale(), Localizer::baseName()) remain useful for debugging.
  • Middleware logs (e.g., RedirectLocale) can be enabled for troubleshooting redirects.

Support

• Documentation:
  • Updated docs for Route::translate() naming requirements and Wayfinder integration.
  • Migration guide for spatie/laravel-typescript-transformer → Wayfinder.
  • Examples for handling unnamed routes in Route::localize().
• Community:
  • GitHub issues may see increased activity around route naming and Wayfinder migration. Monitor for common pitfalls.
• Deprecation:
  • spatie/laravel-typescript-transformer support is