Laravel-Subdomain-Localization

Subdomain localization support for Laravel

| Laravel | laravel-subdomain-localization | Lifecycle | |---|---|---| | ^5.5 | ^5.5 | January 24, 2017 | ||| Bug fixes until January 2019 | ||| Security fixes until June 2020 | | ^5.6 | ^5.6 | February 7, 2018 | ||| 6 months of bug fixes | ||| 1 year of security |

Table of Contents

• Installation
• Usage
  • Locale detection
  • Middleware
  • Route translation
• Configuration
  • Configuration file
  • Configuration values
• Useful functions
• Changelog
• License

Installation

Install with composer

composer require hoyvoy/laravel-subdomain-localization

From Laravel 5.5 onwards, it's possible to take advantage of auto-discovery of the service provider. For Laravel versions before 5.5, you must register the service provider in your config/app.php

Hoyvoy\Localization\LocalizationServiceProvider::class,

Laravel-Subdomain-Localization comes with 2 facades: Localize and Router.

If you want to use them, open config/app.php and add the following lines to the aliases array:

	...
    'Localize'  => Hoyvoy\Localization\Facades\Localize::class,
    'Router'    => Hoyvoy\Localization\Facades\Router::class,
	...

Laravel comes with a middleware that can be used to enforce the use of a language subdomain.

If you want to use it, open app/Http/kernel.php and register this route middleware by adding it to the routeMiddleware array:

	...
    'localize' => \Hoyvoy\Localization\Middleware\Localization::class,
	...

Usage

Locale detection

Open app/Providers/RouteServiceProvider.php and add a call to detectLocale() from the boot method. For example, using the facade:

	...
	use Hoyvoy\Localization\Facades\Localize;
	...
    public function boot(Router $router)
    {
        // This will guess a locale from the current HTTP request
        // and set the application locale
        Localize::detectLocale();
        
        parent::boot($router);
    }
	...

Once you have done this, there is nothing more that you MUST do. Laravel application locale has been set and you can use other locale-dependant Laravel components (e.g. Translation) as you normally do.

Middleware

If you want to enforce the use of a language subdomain for some routes, you can simply assign the middleware provided, for example as follows in app/Http/routes.php:

    // Without the localize middleware, this route can be reached with or without language subdomain
    Route::get('logout', 'AuthController@logout');
    
    // With the localize middleware, this route cannot be reached without language subdomain
    Route::group([ 'middleware' => [ 'localize' ]], function() {
    
        Route::get('welcome', 'WelcomeController@index');
    
    });

For more information about Middleware, please refer to Laravel docs.

Route translation

If you want to use translated routes (en.yourdomain.com/welcome, fr.yourdomain.com/bienvenue), proceed as follows:

First, create language files for the languages that you support:

resources/lang/en/routes.php:

    return [
    
        // route name => route translation
        'welcome' => 'welcome',
        'user_profile' => 'user/{username}',
    
    ];

resources/lang/fr/routes.php:

    return [
    
        // route name => route translation
        'welcome' => 'bienvenue',
        'user_profile' => 'utilisateur/{username}',
    
    ];

Then, here is how you define translated routes in app/Http/routes.php:

    Route::group([ 'middleware' => [ 'localize' ]], function() {
    
        Route::get(Router::resolve('routes.welcome'), 'WelcomeController@index');
    
    });

You can of course name the language files as you wish, and pass the proper prefix (routes. in the example) to the resolve() method.

Configuration

Configuration file

In order to edit the default package configuration, you can run the following artisan command:

php artisan vendor:publish --provider="Hoyvoy\Localization\LocalizationServiceProvider" --tag="config"

Once you have done that, you will find the config file at config/localization.php.

Configuration values

• available_locales (default: ['en', 'de'])

An array of the locales accepted by the routing system.

• cookie_localization (default: true)

Use this option to enable or disable the use of cookies during the locale detection.

• browser_localization (default: true)

Use this option to enable or disable the use of the browser settings during the locale detection.

• cookie_name (default: 'locale')

Here you may change the name of the cookie used to save the locale. This option is used only if localization with cookie is enabled.

• domain (default: env('DOMAIN'))

Here you may change the name of the domain used in your application. By default, the domain is read from the .env file.

• aliases (defaults to empty array)

You can specify aliases to use custom subdomains instead of locale codes.

Example: ['german' => 'de'] means that german.mydomain.dev sets locale to de and if locale is set to de, routes will be prefixed with german. instead of de.

Useful functions

The package provides useful functions that you can use - for example - in your views:

Translate current URL

    <a href="{{ Router::current('fr') }}">See the french version</a>

Use Router::current(string $locale) this to generate an alternate version of the current route. This will return an url with the proper subdomain and also translate the uri if necessary.

Get alternate versions of the current URL

    @foreach (Router::getCurrentVersions() as $locale => $url)
    <a href="{{ $url }}">{{ $locale }}</a>
    @endforeach

Use Router::getCurrentVersions(bool $excludeCurrentLocale = true) to fetch all localized versions of the current route. This will return an array of $locale => $url items that you can use to generate links to alternate versions.

You can pass false as parameter for $excludeCurrentLocale to let function also returns an item for the current locale.

Get localized version for a given route

    <a href="{{ Router::url('user_profile', [ 'username' => 'JohnDoe' ], 'fr') }}">See JohnDoe's profile</a>

Use Router::url($routeName, $routeAttributes = null, $locale = null) to generate an alternate version of the given route. This will return an url with the proper subdomain and also translate the uri if necessary.

You can pass route parameters if necessary. If you don't give a specific locale, it will use the current locale.

Changelog

To see what has changed in recent versions, see the CHANGELOG.

License

This package is licensed under the MIT license.