Product Decisions This Supports

Globalization Strategy: Enables a seamless, multi-lingual experience without manual route duplication (e.g., /about → /en/about, /de/about). Reduces technical debt by centralizing locale logic in a single package.
Roadmap Priorities:
- Phase 1: Launch core features with a single default locale (e.g., English) and expand later.
- Phase 2: Add dynamic locale switching (e.g., language toggles, user preferences) using this package’s RedirectLocale middleware and detector chain.
- Phase 3: Integrate with frontend frameworks (e.g., Inertia.js, Livewire) via Ziggy/Wayfinder adapters to sync client-side routes with server-side locales.
Build vs. Buy:
- Buy: Avoids reinventing locale detection, URL redirection, and route prefixing. Leverages battle-tested code (successor to mcamara/laravel-localization).
- Build: Only if needing custom locale logic (e.g., non-standard URL patterns, non-BCP 47 locales) beyond the package’s scope.
Use Cases:
- Multilingual Web Apps: E-commerce, SaaS platforms, or content sites targeting international audiences.
- Regional Compliance: Localized legal/privacy pages (e.g., /de/datenschutz).
- User Preferences: Respecting browser/device language settings or user-selected locales.
- SEO: Canonical URLs with locale prefixes (e.g., hreflang tags) via localizedUrl() helpers.

When to Consider This Package

Adopt If:
- Your Laravel app requires dynamic locale-aware routing (auto-detection + redirection) without hardcoding routes per language.
- You need compatibility with route:cache (static routes) and Ziggy/Inertia.js for SPA support.
- Your team lacks bandwidth to maintain custom locale logic (e.g., middleware, route macros, or URL generators).
- You prioritize developer experience (e.g., route('about') works regardless of locale) and consistency (e.g., RTL/LTR direction handling).
- Your app uses Laravel 9+ and PHP 8.2+ (package’s supported versions).
Look Elsewhere If:
- You need non-standard locale patterns (e.g., /locale/code/page instead of /code/page). This package enforces {locale}/route syntax.
- Your app requires subdomain-based localization (e.g., de.example.com). Use packages like spatie/laravel-localization or custom middleware.
- You’re using Laravel <9 or PHP <8.2. The package drops legacy support.
- Your locale logic is highly custom (e.g., locale-specific APIs, non-URL-based detection). Consider a lightweight wrapper around Laravel’s built-in App::setLocale().
- You need serverless/edge caching (e.g., Cloudflare Workers). The package relies on session/cookie-based locale persistence, which may conflict with edge caching.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us launch a multilingual version of [Product] with minimal engineering effort. Instead of manually creating /en/about, /de/about, etc., we’ll use auto-detection (browser language) and seamless redirection to serve the right locale—without duplicating routes or breaking SEO. It’s used by [X] companies and integrates with our existing stack (Laravel, Inertia.js). The cost? Zero upfront dev time; the benefit? Faster time-to-market for global audiences and compliance with regional requirements."

Key Outcomes:

Reduce dev time by 80% vs. custom locale routing.
Improve UX with persistent locale preferences (cookies/session).
Future-proof for new languages without refactoring.

For Engineering:

"Laravel Localizer solves our locale routing pain points cleanly*:

Auto-detect + Redirect: Uses Accept-Language headers to redirect users to /de/about (or /en/about if default) on first visit.
Ziggy/Inertia Support: Works out-of-the-box with @routes Blade directives and client-side routing (no manual JS hacks).
RTL/LTR Handling: Automatically sets <html dir="rtl"> for Arabic/Hebrew locales via Localizer::currentLocaleDirection().
Route Consistency: route('about') always resolves correctly, even after locale changes. No more route('de.about') sprawl.
Performance: Compatible with route:cache and adds negligible overhead (~1ms per request).

Trade-offs:

Lock-in: Uses {locale}/route syntax (not /locale=de&route=about).
Customization: Limited if you need non-standard locale patterns (e.g., API endpoints).

Migration Path:

Replace any custom locale middleware with RedirectLocale + SetLocale.
Update route() calls in Blade/JS to rely on the package’s helpers.
Test edge cases: stale bookmarks (e.g., /EN/about → redirects to /en/about), query string preservation during locale switches.

Alternatives Considered:

Roll our own: 2–3 weeks of dev time; higher maintenance risk.
Spatie’s package: Subdomain-based localization (not our use case).
No solution: Manual routes → technical debt and scaling issues.

Recommendation: Adopt for MVP, then extend with custom detectors (e.g., user profile-based locales) or middleware if needed."*

Laravel Localizer Laravel Package

Product Decisions This Supports

When to Consider This Package

How to Pitch It (Stakeholders)

For Executives:

For Engineering: