Localization for Laravel framework

0.5.0 2019-02-28 13:54 UTC


Build Status Total Downloads Latest Stable Version License


The Laravel Localization package is built for Laravel 5.5+ and provides:

  • Localized routes with language URL prefixes.
  • Domain based localized routes.
  • Middleware to detect user language based on HTTP header and session.
  • Redirect the user to the localized version.
  • Possibility to hide the language URL prefix for the default language.
  • Possibility to localize a subset of routes only.
  • Language Switcher and Hreflang Meta Tags
  • Patched route() method to use localized routes whenever possible.
  • Compatibility with artisan route:cache.


To get started, use Composer to add the package to your project's dependencies:

composer require josiasmontag/laravel-localization

In Laravel 5.5 the service provider will automatically get registered. In older versions of the framework just register the Service Provider and the the Localization Facade in your config/app.php configuration file:

    'providers' => [
        // Other service providers...

    // ...

    'aliases' => [
        // Other Facades
        'Localization' => \Lunaweb\Localization\Facades\Localization::class,


Add the HandleLocalization Middleware to the web group in App/Http/Kernel.php:

    protected $middlewareGroups = [
        'web' => [
            // Other Middleware


To publish the config file to config/localization.php:

php artisan vendor:publish --provider "Lunaweb\Localization\LocalizationServiceProvider"

Default configuration:

return [
    // Add any language you want to support
    'locales' => [
        'en' => ['name' => 'English', 'script' => 'Latn', 'native' => 'English', 'regional' => 'en_GB'],
        'de' => ['name' => 'German', 'script' => 'Latn', 'native' => 'Deutsch', 'regional' => 'de_DE'],

    // The default locale is configured in config/app.php (locale)

    // Default locale will not be shown in the url.
    // If enabled and 'en' is the default language:
    // / -> English page, /de -> German page
    // If disabled:
    // /en -> English Page, /de -> German page
    'hide_default_locale_in_url' => true,

    // Use query parameter if there are no localized routes available.
    // Set it to null to disable usage of query parameter.
    'locale_query_parameter' => 'hl',

    // Enable redirect if there is a localized route available and the user locale was detected (via HTTP header or session)
    'redirect_to_localized_route' =>  true,

    // Try to detect user locale via Accept-Language header.
    'detect_via_http_header' => true,

    // Remember the user locale using session.
    'detect_via_session' => true,



Prefix Based Localized Routes

To add localized routes with language prefixes, edit your routes/web.php and use localizedRoutesGroup helper:

Localization::localizedRoutesGroup(function() {
    Route::get('/', 'HomeController@uploadDocuments')->name('index');
    Route::get('/register', 'RegisterController@showRegisterForm')->name('register');

Under the hood this will create the following routes for you:

Route Route Name Language
/ index English (Default Language)
/de de.index German
/fr fr.index French
/register register English (Default Language)
/de/register de.register German
/fr/register fr.register French

Domain Based Localized Routes

To add domain-based localized routes, add the localized domains to your config/localization.php configuration:

'locales' => [
   'en' => ['domain'=> '', 'name' => 'English'],
   'de' => ['domain'=> '', 'name' => 'German'],
   'fr' => ['domain'=> '', 'name' => 'French'],

The example from above will then create the following routes:

Route Route Name Language index English (Default Language) de.index German fr.index French register English (Default Language) de.register German fr.register French

Localization Specific Routes

You can manually create language specific routes using the localization() macro.

Route::get('/contact', 'ContactController@showContactForm')
Route::get('/kontakt', 'ContactController@showContactForm')


Localized route()

route() will automatically use the localized version, if there is any available. Using the example from above, route('index') resolves to the index, de.index or fr.index route depending on the user's language.

Check if the current route is localized



Route::current()->getLocalization() === null

Get the localization of the current route


Get the URL to a different language version of the current route


Get the route name to a different language version of the current route


Hreflang Meta Tags

   @foreach(Localization::getLocales() as $localeCode => $properties)
        <link rel="alternate" hreflang="{{ $localeCode }}" href="{{ Localization::getLocaleUrl($localeCode) }}">

Language Switcher

    @foreach(Localization::getLocales() as $localeCode => $properties)
            <a rel="alternate" hreflang="{{ $localeCode }}" href="{{ Localization::getLocaleUrl($localeCode, true) }}">
                 {{ $properties['native'] }} </a>