Download the PHP package laraveledge/laravel-locale without Composer

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

• 🚀 Installation
• ⚙️ Configuration
• 🧩 Usage
• 📌 Alias Usage
• 🚦 Middleware Setup
• 🧠 Locale Detection Order
• ⚠️ Edge Cases
• ✅ What This Package Does
• 📁 Folder Structure
• ✅ Requirements
• 📄 License

🚀 Installation

Install via Composer:

⚙️ Configuration

Publish the configuration file:

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

🧩 Usage

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

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

📌 Alias Usage

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

🚦 Middleware Setup

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

🚦 Full Setup (Copy Paste) - Recommended:

🧠 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

• 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.

✅ 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

This package is inspired by:

• mcamara/laravel-localization
• codezero/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

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)

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

🚀 Just Use It — You’ll Feel the Difference

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

📁 Folder Structure

✅ Requirements

• PHP 8.1+
• Laravel 10+

📄 License

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