hoyvoy/laravel-subdomain-localization

Subdomain localization support for Laravel

, _(*1)

Laravel-Subdomain-Localization

Subdomain localization support for Laravel, _(*2)

Table of Contents

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

Installation

Install with composer, _(*3)

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, _(*4)

Hoyvoy\Localization\LocalizationServiceProvider::class,

Laravel-Subdomain-Localization comes with 2 facades: Localize and Router., _(*5)

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

    ...
    '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., _(*7)

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

    ...
    '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:, _(*9)

    ...
    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., _(*10)

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:, _(*11)

    // 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., _(*12)

Route translation

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

First, create language files for the languages that you support:, _(*14)

resources/lang/en/routes.php:, _(*15)

    return [

        // route name => route translation
        'welcome' => 'welcome',
        'user_profile' => 'user/{username}',

    ];

resources/lang/fr/routes.php:, _(*16)

    return [

        // route name => route translation
        'welcome' => 'bienvenue',
        'user_profile' => 'utilisateur/{username}',

    ];

Then, here is how you define translated routes in app/Http/routes.php:, _(*17)

    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., _(*18)

Configuration

Configuration file

In order to edit the default package configuration, you can run the following artisan command:, _(*19)

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., _(*20)

Configuration values

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

An array of the locales accepted by the routing system., _(*21)

• cookie_localization (default: true)

Use this option to enable or disable the use of cookies during the locale detection., _(*22)

• browser_localization (default: true)

Use this option to enable or disable the use of the browser settings during the locale detection., _(*23)

• 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., _(*24)

• 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., _(*25)

• aliases (defaults to empty array)

You can specify aliases to use custom subdomains instead of locale codes., _(*26)

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., _(*27)

Useful functions

The package provides useful functions that you can use - for example - in your views:, _(*28)

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., _(*29)

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., _(*30)

You can pass false as parameter for $excludeCurrentLocale to let function also returns an item for the current locale., _(*31)

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., _(*32)

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

Changelog

To see what has changed in recent versions, see the CHANGELOG., _(*34)

License

This package is licensed under the MIT license., _(*35)