PHPackages                             laraveledge/laravel-locale - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. laraveledge/laravel-locale

ActiveLibrary[Localization & i18n](/categories/localization)

laraveledge/laravel-locale
==========================

Elegant URL-based locale handler and middleware for Laravel.

v1.9.0(1y ago)29MITPHPPHP ^8.1

Since Jul 3Pushed 1y agoCompare

[ Source](https://github.com/laravelEdge/laravel-locale)[ Packagist](https://packagist.org/packages/laraveledge/laravel-locale)[ RSS](/packages/laraveledge-laravel-locale/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (5)Versions (10)Used By (0)

Laravel Locale
==============

[](#laravel-locale)

Elegant URL-Based Localization for Laravel Applications

**Laravel Locale** is a simple yet powerful package for handling localization through URL segments in Laravel. It detects, validates, and manages locale slugs (e.g., `/en`, `/tr`) in the request path, with seamless support for session storage, normalization, and middleware-based behavior.

---

📚 Table of Contents
-------------------

[](#-table-of-contents)

- [🚀 Installation](#-installation)
- [⚙️ Configuration](#-configuration)
- [🧩 Usage](#-usage)
- [📌 Alias Usage](#-alias-usage)
- [🚦 Middleware Setup](#-middleware-setup)
- [🧠 Locale Detection Order](#-locale-detection-order)
- [⚠️ Edge Cases](#-edge-cases)
- [✅ What This Package Does](#-what-this-package-does)
- [📁 Folder Structure](#-folder-structure)
- [✅ Requirements](#-requirements)
- [📄 License](#-license)

---

🚀 Installation
==============

[](#-installation)

Install via Composer:

```
composer require laraveledge/laravel-locale
```

---

⚙️ Configuration
----------------

[](#️-configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=laravel-locale-config
```

This will publish `config/locale.php`, where you can specify your supported locales:

```
return [
    'supported_locales' => ['en', 'tr', 'ur'],
];
```

---

🧩 Usage
-------

[](#-usage)

Wrap your localized routes using middleware and a `{locale}` prefix:

```
use Laraveledge\LaravelLocale\Middleware\SetLocale;
use Laraveledge\LaravelLocale\Middleware\EnsureIsLocale;
use Laraveledge\LaravelLocale\Middleware\SetDefaultLocaleForUrls;

Route::group([
    'prefix' => '{locale}',
    'middleware' => [
        EnsureIsLocale::class,
        SetLocale::class,
        SetDefaultLocaleForUrls::class,
        'web',
    ],
], function () {
    Route::get('/', fn () => 'Home Page')->name('home');
    Route::get('/about', fn () => 'About Page');
    Route::get('/test', fn () => 'Test Page')->name('test');

    Route::fallback(function () {
        abort(404, 'Hm, why did you land here somehow?');
    }); //Neccessary , why ? see Edge Cases below
});
```

Now visit `/`, `/about`, or `/test` to be redirected to the localized versions.

---

📌 Alias Usage
-------------

[](#-alias-usage)

You can also register aliases in `bootstrap/app.php` to avoid referencing class paths directly:

```
use Laraveledge\LaravelLocale\Middleware\SetLocale;
use Laraveledge\LaravelLocale\Middleware\EnsureIsLocale;
use Laraveledge\LaravelLocale\Middleware\SetDefaultLocaleForUrls;

->withMiddleware(function (Middleware $middleware): void {
    $middleware->alias([
        'ensureIsLocale' => EnsureIsLocale::class,
        'redirectMissingLocale' => RedirectMissingLocale::class,
        'setDefaultUrls' => SetDefaultLocaleForUrls::class,
        'setLocale' => SetLocale::class,
    ]);
});
```

---

🚦 Middleware Setup
------------------

[](#-middleware-setup)

To avoid conflicts with Laravel’s internal URL binding, make sure to set middleware priority properly:

```
use Illuminate\Routing\Middleware\SubstituteBindings;

->withMiddleware(function (Middleware $middleware) {
    $middleware->prependToPriorityList(
        before: SubstituteBindings::class,
        prepend: SetDefaultLocaleForUrls::class,
    );
});
```

🚦 Full Setup (Copy Paste) - Recommended:
----------------------------------------

[](#-full-setup-copy-paste---recommended)

```
bootstrap/app.php:

use Illuminate\Routing\Middleware\SubstituteBindings;
use Laraveledge\LaravelLocale\Middleware\SetLocale;
use Laraveledge\LaravelLocale\Middleware\EnsureIsLocale;
use Laraveledge\LaravelLocale\Middleware\SetDefaultLocaleForUrls;

   ->withMiddleware(function (Middleware $middleware): void {
     $middleware->prependToPriorityList(
        before: SubstituteBindings::class,
        prepend: SetDefaultLocaleForUrls::class,
    );
    $middleware->alias([
            'ensureIsLocale' => EnsureIsLocale::class,
            'setDefaultUrls' => SetDefaultLocaleForUrls::class,
            'setLocale' => SetLocale::class,
    ]);
})

web.php:
        Route::group([
                'prefix' => '{locale}',
                'middleware' => ['web', 'ensureIsLocale', 'setLocale', 'setDefaultUrls'] // ensure this middleware order
        ], function () {

 Route::get('/', function () {
                    return 'home';
     });

    Route::get('/about', function () {
                    return 'products';
    });

Route::get('/test', function(){
return 'test';
})->name('test'); //ensure a route named test is present in your routes so you can check/test the Locale::debug() mnethod

   Route::fallback(function () {
        abort(404, 'Hm, why did you land here somehow?');
    }); //Neccessary , why ? see Edge Cases below

});
```

🧠 Locale Detection Order
------------------------

[](#-locale-detection-order)

The package detects locale using the following order:

1. **Session** – If a locale exists in session, it is used.
2. **URL Segment** – First segment of the path.
3. **Browser Preferred Language** – Based on `Accept-Language` header.
4. **Fallback Locale** – As defined in `app.fallback_locale`.

---

⚠️ Edge Cases
-------------

[](#️-edge-cases)

- If your route is deeply nested like /products/1 and the locale is missing, Laravel may return a 404 before your middleware is ever triggered. This happens because Laravel tries to match the route as-is (e.g., /products/1), but it doesn't exist without a {locale} prefix, so it aborts with a 404 before even hitting the middleware stack.
- However, if you define a Route::fallback() inside your localized group, Laravel is then forced to execute the fallback when no route matches. This allows the middleware to still kick in and redirect appropriately.
- Without a fallback, shallow routes like /products will still work because Laravel can find a matching route and then the middleware handles it. But deep, parameterized routes like /products/1 will fail silently unless the fallback is present.

✅ Solution: Always define a Route::fallback() within your {locale} route group to ensure nested and parameterized routes also get redirected when the locale is missing.

```
Route::fallback(function () {
    abort(404, 'Hm, why did you land here somehow?');
});

---
```

✅ What This Package Does
------------------------

[](#-what-this-package-does)

- ✅ Detects and validates the locale segment in the URL
- 🔠 Normalizes casing (e.g., `EN-us` → `en`)
- 💾 Stores the selected locale in session
- 🌍 Calls `App::setLocale(...)`
- 🔁 Redirects to localized URLs if missing or invalid

---

🙌 Inspired by the Greats — Built with Simplicity
------------------------------------------------

[](#-inspired-by-the-greats--built-with-simplicity)

This package is inspired by:

- [`mcamara/laravel-localization`](https://github.com/mcamara/laravel-localization)
- [`codezero/laravel-localized-routes`](https://github.com/codezero-be/laravel-localized-routes)

These packages have served the Laravel ecosystem well and offer a wide range of features. However, as Laravel modernized its routing and middleware pipeline, we felt the need for a **simpler, lighter**, and **middleware-first** approach — without route macros or runtime route manipulation.

---

🎯 Why This Package Exists
-------------------------

[](#-why-this-package-exists)

In real-world projects:

- `mcamara` dynamically registers routes at runtime, which can introduce unpredictable behavior and confusion.
- `codezero` uses route macros and abstractions which deviate from native Laravel patterns.

This package solves that by offering:

✅ Clean, Laravel-native routing
✅ No macros — just plain `Route::get()` and `Route::group()`
✅ Middleware-first lifecycle control
✅ SEO-optimized URL redirection and normalization
✅ Works great with Livewire, Inertia, Blade, APIs, SPAs
✅ Debug-friendly (`Locale::debug()`)
✅ Lightweight, transparent, and easy to extend

---

📦 What This Package Is (and Isn't)
----------------------------------

[](#-what-this-package-is-and-isnt)

This package **intentionally starts simple**.

It currently **does not offer** some of the advanced features available in `mcamara` or `codezero` such as:

- Automatic route translation
- Locale-prefixed route generation
- URL version negotiation, etc.

We plan to add more features in future versions — while staying true to the Laravel philosophy of **clarity over magic**.

---

🧠 Choose Based on Your Needs
----------------------------

[](#-choose-based-on-your-needs)

|-----------------------------------|----------------------------------------| | You Should Use This Package If...| |-----------------------------------|----------------------------------------| | You want a lightweight, zero-config localization system | You prefer Laravel-native routes with no macros | You value predictable middleware-based flow | You’re building something new and modern |-----------------------------------|----------------------------------------| | You Might Prefer Other Packages If... | |-----------------------------------|----------------------------------------| | You need automatic route translation | You don’t mind learning route macros | You need deeply integrated i18n features | You’re maintaining legacy systems

---

🚀 Just Use It — You’ll Feel the Difference
------------------------------------------

[](#-just-use-it--youll-feel-the-difference)

Install it, add middleware, define routes — and you’re done.

```
Route::group([
    'prefix' => '{locale}',
    'middleware' => ['web', 'ensureIsLocale', 'setLocale', 'setDefaultUrls']
], function () {
    Route::get('/', fn () => view('home'))->name('home');
});
```

📁 Folder Structure
------------------

[](#-folder-structure)

```
src/
├── Config/
│   └── locale.php
├── Middleware/
│   ├── EnsureIsLocale.php
│   ├── SetLocale.php
│   └── SetDefaultLocaleForUrls.php
├── Services/
│   └── LocaleService.php
├── Facades/
│   └── Locale.php (optional)
└── LaravelLocaleServiceProvider.php

```

---

✅ Requirements
--------------

[](#-requirements)

- PHP 8.1+
- Laravel 10+

---

📄 License
---------

[](#-license)

This package is open-source and released under the MIT License.

###  Health Score

31

—

LowBetter than 66% of packages

Maintenance50

Moderate activity, may be stable

Popularity8

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 50% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

9

Last Release

366d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/c5e269bdd521bf886aac952838bd0b69b86fdb2196154dd6c45a47c8e4b90320?d=identicon)[Shaharyar-WebDev](/maintainers/Shaharyar-WebDev)

---

Top Contributors

[![shaharyarhq](https://avatars.githubusercontent.com/u/198033945?v=4)](https://github.com/shaharyarhq "shaharyarhq (23 commits)")[![Shaharyar-WebDev](https://avatars.githubusercontent.com/u/198033945?v=4)](https://github.com/Shaharyar-WebDev "Shaharyar-WebDev (23 commits)")

---

Tags

phplaravellocalizationlanguageroutestranslationroutinglocalecountry

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/laraveledge-laravel-locale/health.svg)

```
[![Health](https://phpackages.com/badges/laraveledge-laravel-locale/health.svg)](https://phpackages.com/packages/laraveledge-laravel-locale)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[codezero/laravel-localized-routes

A convenient way to set up, manage and use localized routes in a Laravel app.

544664.5k4](/packages/codezero-laravel-localized-routes)[opgginc/codezero-laravel-localized-routes

A convenient way to set up, manage and use localized routes in a Laravel app.

29119.1k1](/packages/opgginc-codezero-laravel-localized-routes)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[api-platform/laravel

API Platform support for Laravel

58171.6k14](/packages/api-platform-laravel)[niels-numbers/laravel-localizer

Detects the user’s preferred language and redirects to the matching localized URL.

183.4k](/packages/niels-numbers-laravel-localizer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)