alexwaha/laravel-multilang-routes

Multilanguage Localization for Laravel routes.

1.1.1 2025-04-13 09:01 UTC

Requires

• php: >=8.1
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.22
• mockery/mockery: ^1.6
• pestphp/pest: ^3.8
• phpstan/extension-installer: ^1.3

Conflicts

• symfony/console: <6.4

MIT

• Alex Vakhovski
• Bug Report

• routes
• laravel
• localization
• multilingual
• localize

README

Simple and lightweight package to localize your Laravel routes.

Features

• Localized versions of your routes without complex configurations
• Seamless support for route groups, slugs, and middleware
• Automatically switches URLs based on the active locale
• Redirects /fallback_locale/... to /... with 301 if needed
• Works with Laravel 10, 11, and 12

📚 Installation

Install the package via Composer:

composer require alexwaha/laravel-multilang-routes

Publish the configuration file:

php artisan vendor:publish --tag=multilang-routes-config

This will create config/multilang-routes.php.

🚀 Usage

Define your routes using the localizedRoutes macro.

use Illuminate\Support\Facades\Route;

Route::localizedRoutes(function () {
    Route::get('/', function () {
        return view('welcome');
    });
});

Or routes with middlewares, for ex.: web

use Illuminate\Support\Facades\Route;

Route::localizedRoutes(function () {
    Route::get('/', [HomeController::class, 'index'])->name('home');
}, ['web']);

Or named routes with prefix

Route::localizedRoutes(function () {
    Route::name('blog.')->prefix('/blog')->group(function () {
        Route::get('', [BlogController::class, 'index'])->name('index');
        Route::get('/{post}', [BlogController::class, 'show'])->name('show');
    });
}, ['web']);

This automatically generates localized routes like:

• /en/blog
• /es/blog
• /de/blog

The slug in the URL is required for the setLocale middleware, which changes the application language based on the locale slug.

🧩 Checking if Route is Localized

You can easily check if your route name is already localized:

@if (Route::isLocalized($name))
    // The route name is already localized (e.g., "en.blog.index")
@endif

Blade usage

Generate a localized URL in Blade templates using Route::localize() method:

<a href="{{ Route::localize('about') }}">About</a>

Or generate URLs with parameters:

<a href="{{ Route::localize('blog.show', ['post' => $post]) }}">View Post</a>

🛡️ Middleware

🧩 localize.setLocale

Middleware to automatically detect and set the application locale based on the first segment of the URL.

Registered alias as localize.setLocale

Note: If the segment does not match any configured language slug, the application will fall back to the default locale.

➊ Apply Middleware Globally to a middleware group

in Laravel 10.x app\Http\Kernel.php

protected $middlewareGroups = [
        'web' => [
            \Alexwaha\Localize\Middleware\SetLocale::class,

in Laravel ^11.x bootstrap\app.php

    ->withMiddleware(function (Middleware $middleware) {
        $middleware->group('web', [
            \Alexwaha\Localize\Middleware\SetLocale::class,,
        ]);
    })

Route::localizedRoutes(function () {
    Route::get('/', function () {
        return view('welcome');
    });
}, ['web']);

➋ Apply Middleware Directly in localizedRoutes You can pass middleware as the second argument to the localizedRoutes macro:

Route::localizedRoutes(function () {
    Route::get('/', function () {
        return view('welcome');
    });
}, ['web', 'localize.setLocale']);

This is a simpler and more compact approach, especially useful for smaller projects.

🧩 PaginatedMiddleware

Middleware that transforms paginated URLs by cleaning query parameters.

Registered alias as localize.paginated.

When a paginated route like /page/{page?} is used:

🛠 Note:

• It ensures that the first page blog/page/1 does not have a query string or URL segment like /page/1.
• Instead, the first page URL is clean, such as /blog, improving SEO and URL readability.
• If the user accesses blog/page/2, blog/page/3, etc., the page number remains in the URL.

When building localized URLs with pagination, you can define your routes like this:

use Illuminate\Support\Facades\Route;

Route::localizedRoutes(function () {
    Route::name('blog.')->prefix('/blog')->group(function () {
        Route::get('', [BlogController::class, 'index'])->name('index');
        Route::get('/page/{page?}', [BlogController::class, 'index'])->name('paginated');
        Route::get('/{post}', [BlogController::class, 'show'])->name('show');
    });
}, ['web', 'localize.setLocale', 'localize.paginated']);

Default Locale Redirection

If a user visits a URL with the default fallback locale (e.g., /en/about when en is the fallback), they will be automatically redirected with a 301 Permanent Redirect to the non-sluged version (/about).

This ensures clean URLs for your default language.

⚙️ Configuration

You can configure which languages are available and their corresponding URL slugs inside the config/multilang-routes.php file.

Each language entry should contain:

Key	Description	Example
locale	Application locale (app()->setLocale)	en,es,de
slug	URL slug for routes	en,es,de | english, spanish, german

Example:

return [
    'language_provider' => [
        'class' => \Alexwaha\Localize\LanguageProvider::class,
        'params' => [
            'languages' => [
                [
                    'locale' => 'en',
                    'slug' => 'en',
                ],
                [
                    'locale' => 'es',
                    'slug' => 'es',
                ],
            ],
        ],
    ],
];

You can customize the list of supported languages and their URL prefixes or create your own Language Provider.

If you want full control over how languages are loaded (for example, from a database), you can create a custom provider by implementing the LanguageProviderInterface and specify your class in the configuration.

Example config/multilang-routes.php:

return [
    'language_provider' => [
        'class' => App\Providers\CustomLanguageProvider::class,
    ],
];

Your custom provider should implement:

interface LanguageProviderInterface
{
    public function getLanguages(): array;
    public function getLocaleBySegment(?string $segment = null): string;
}

This gives you the flexibility to load languages from the database, API, or any other source.

📂 Examples

You can find practical examples inside the examples folder:

• ExampleController.php
  Simple controller with paginated navigation.

• DatabaseLanguageProvider.php
  Custom Language Provider loading languages from database.

• RoutesExample.php
  Localized routes registration example.

• pagination.blade.php
  Blade pagination rendering.

Requirements

• PHP >= 8.2
• Laravel 10.x, 11.x, or 12.x

License

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

Credits

Developed by Alex Waha

Feel free to submit issues or contribute to this project!