Download the PHP package mikemenard/laravel-localization without Composer

Laravel Localization

A modern, flexible Laravel package for URL-based localization with seamless Livewire and third-party package support.

Why This Package?

Most Laravel localization packages force you to wrap all your routes in localized groups, breaking compatibility with Livewire and third-party packages that generate their own URLs. This package takes a different approach.

The Solution:

Instead of requiring every route to be in a localized group, this package uses:

1. A single global middleware assigned to the web group that sets the locale and URL::defaults() for every request
2. Session-based persistence that remembers the user's locale choice
3. Optional route-specific middleware for routes that need locale prefixes

This architecture means:

• ✅ route('profile') automatically generates /fr/profile when French is active
• ✅ Livewire components work without modification
• ✅ Third-party packages (Filament, Nova, etc.) respect the current locale
• ✅ No need to wrap every single route in a localized group
• ✅ Session persistence works across the entire application

Features

• 🌍 URL-based localization with configurable route parameters
• 🔄 Automatic URL generation via URL::defaults() - no manual locale passing needed
• 💾 Session persistence - remembers user locale preference
• 🎯 Smart locale resolution - session → browser headers → app default
• 🔗 Livewire compatible - works seamlessly with Livewire navigation
• 📦 Third-party friendly - packages automatically use the current locale
• 🎨 Clean route macro - Route::localized() for prefix-based routes
• 🛡️ Strict enforcement - optional middleware for canonical URL redirects
• 🔧 Extensible Locale DTO - add custom properties via magic methods
• ⚡ Zero configuration - works out of the box with sensible defaults

Requirements

• PHP 8.4+
• Laravel 10+

Installation

Install the package via Composer:

The package will automatically register via Laravel's package auto-discovery.

Publish the configuration file (optional):

Quick Start

1. Add the Global Middleware

Add the Localize middleware to your web middleware group in bootstrap/app.php:

Important: Use prepend instead of append to ensure the Localize middleware runs before other middleware (like authentication). This ensures that URL::defaults() is set before any route generation occurs, making locale parameters automatically available for auth redirects and other middleware that generate URLs.

2. Define Your Locales

Edit config/localization.php:

3. Create Localized Routes

Use the Route::localized() macro for routes that should have locale prefixes:

This generates:

• /en/ → English homepage
• /fr/ → French homepage
• /en/about → English about page
• /fr/about → French about page

4. Add a Language Switcher (example)

Create a Blade component at resources/views/components/language-switcher.blade.php:

Use it in your layout:

Configuration

The configuration file provides three main options:

Supported Locales

Define all locales your application supports:

Each locale requires:

• Key: The locale code (e.g., 'en', 'fr-ca') - normalized to lowercase with hyphens
• label: Display name for the language switcher
• language: Language code for the locale

You can add custom properties that will be accessible via the Locale DTO:

Access custom properties:

Route Parameter

Customize the route parameter name used in URLs:

Validation: Must be a single word (alphanumeric and underscores only) - no slashes or special characters.

This affects:

• URL structure: /{locale}/about vs /{lang}/about
• Route parameters: route('about', ['locale' => 'fr']) vs route('about', ['lang' => 'fr'])

Locale Class

Specify a custom Locale DTO class:

Your custom class must extend \Mikemenard\Localization\Locale:

How It Works: The Two-Middleware System

This package uses two middleware classes for different purposes:

1. Localize Middleware (Global)

Purpose: Sets the locale for every request and makes URL generation work automatically.

Added to: web middleware group in bootstrap/app.php

Behavior:

• Extracts locale from the first URL segment (e.g., /fr/about → 'fr')
• Falls back to session → browser headers → app default if no locale in URL
• Calls App::setLocale() to set the application locale
• Calls URL::defaults(['locale' => 'fr']) so all route generation includes the locale
• Saves the locale to session for persistence

Why this matters:

• Makes route('profile') automatically generate /fr/profile when French is active
• Livewire components automatically use the correct locale in their URLs
• Third-party packages respect the current locale without modification
• Session persistence means the locale "sticks" across requests

2. EnforceLocale Middleware (Route-Specific)

Purpose: Enforces locale prefixes and handles redirects for routes that must have a locale.

Added to: Specific route groups via Route::localized() macro or manual route groups

Behavior:

• Validates the locale in the URL is in the correct format
• Redirects to a valid locale if the format is invalid
• Returns 404 if an unsupported locale is requested
• Redirects to canonical locale format (e.g., en_US → en-us)
• Ensures strict URL structure for SEO and consistency

Example:

URLs like /invalid/products get redirected to /en/products (or user's session locale).

Route Macro Usage

The Route::localized() macro simplifies creating localized route groups.

Basic Usage

Equivalent to:

Chainable Middleware

You can chain additional middleware before calling group():

Multiple middleware:

Name Prefixing

Combine with Laravel's name prefixing:

Manual Route Groups (Alternative)

If you prefer not to use the macro, define the group manually:

Language Switcher Component

Create a reusable language switcher component at resources/views/components/language-switcher.blade.php:

Explanation:

• Localization::getLocales() returns all configured locales as Locale DTOs
• Localization::isCurrentLocale($locale) checks if the locale is currently active
• Localization::localizeCurrentUrl($locale) generates the current URL with the locale switched

Advanced Language Switcher

With custom flags and dropdown:

Livewire-Compatible Switcher

If using Livewire with wire:navigate:

Customizing the Locale DTO

The Locale class uses magic methods to allow custom properties.

Adding Custom Properties

In your config:

Access custom properties via magic __get():

Extending the Locale Class

Create a custom Locale class:

Register it in config:

Use custom methods:

API Reference

Facade Methods

All methods are available via the Localization facade:

supported(): array

Returns an array of all supported locale codes.

getLocales(): Collection

Returns a Collection of Locale objects.

currentLocale(): Locale

Returns the Locale object for the current application locale.

setLocale(string|Locale $locale): string

Sets the application locale, updates session, and sets URL defaults.

Throws: UnsupportedLocaleException if locale is not supported.

isSupported(string|Locale|null $locale): bool

Checks if a locale is supported.

isCurrentLocale(string|Locale $locale): bool

Checks if a locale is the current application locale.

localizeCurrentUrl(string|Locale $locale): string

Returns the current URL with the locale switched.

resolveLocale(): string

Resolves the locale from session → browser headers → app default.

getRouteParameter(): string

Returns the configured route parameter name.

isCanonical(string $locale): bool

Checks if a locale is in canonical format (exact match in supported locales).

getLocaleFromUrl(): ?string

Extracts the locale from the current request's route parameter.

isLocale(string $locale): bool

Validates if a string matches the locale format pattern.

Locale DTO Properties

Every Locale object has these properties:

Advanced Usage

Programmatic Locale Switching

In controllers or middleware:

URL Generation

Thanks to URL::defaults() being set automatically, all route helpers work:

Override for a specific locale:

Accessing Session Directly

The package stores locale in session under key localization:locale:

Browser Locale Detection

The package automatically detects browser locale from Accept-Language headers:

Will resolve to 'fr' if no session locale exists.

Locale Fallback Logic

When matching locales, the package uses intelligent fallback:

1. Exact match: 'fr' matches 'fr' in config
2. Prefix match: 'fr' matches 'fr-ca' in config (if no exact match)
3. Language code match: 'fr-ca' matches 'fr' in config (if no exact or prefix match)

Example:

Testing

In tests, you can manually set the locale:

Exception Handling

The package throws descriptive exceptions for common errors:

UnsupportedLocaleException

Thrown when trying to set an unsupported locale:

InvalidRouteParameterException

Thrown when route parameter config is invalid:

InvalidLocaleClassException

Thrown when custom locale class is invalid:

FAQ

Does this replace Laravel's built-in localization?

No, it complements it. Laravel's trans(), __(), and language files still handle translations. This package manages locale selection, URL structure, and session persistence.

Can I use this with Livewire?

Yes! That's one of the main reasons this package exists. The global middleware ensures Livewire respects the current locale without modification.

What about SEO and duplicate content?

Use the EnforceLocale middleware on your localized routes to ensure canonical URLs and automatic redirects. This prevents duplicate content issues.

Can I have non-localized routes?

Absolutely. Only routes inside Route::localized() groups require locale prefixes. Other routes work normally:

How do I handle the root URL /?

Create a redirect to your default or detected locale:

Can I use subdomain-based locales?

Not currently. This package is designed for path-based locales (/en/about, /fr/about).

Does this work with Laravel Jetstream/Breeze?

Yes, but you'll need to wrap their routes in Route::localized() groups if you want localized URLs for auth pages.

License

This package is open-source software licensed under the MIT license.

Credits

Created by Mike Menard.

Built for Laravel 10+ with PHP 8.4+.