Laravel Tongue 👅 - Multilingual subdomain URLs and redirects
, (*1)
, (*2)
, (*3)
If you are looking for an easy package for subdomain multilingual URLs, this package is for you. 😜, (*4)
Old Way: https://example.com/de, https://example.com/fr etc.
New Way: https://de.example.com, https://fr.example.com etc., (*5)
*Prerequisites: PHP ^7.4 || ^8.1 and Laravel ^8.41 || PHP ^8.0.2 and Laravel ^9.0 and Laravel ^10.0
***Older Laravel Versions: Click here, (*6)
Installation in 4 Steps*
1: Add with composer 💻
composer require pmochine/laravel-tongue
2: Publish Configuration File (you need to change some things to use it 😎)
php artisan vendor:publish --provider="Pmochine\LaravelTongue\ServiceProvider" --tag="config"
3: Add the Middleware 🌐
Laravel Tongue comes with a middleware that can be used to enforce the use of a language subdomain. For example the user calls example.com it goes directly to fr.example.com., (*7)
If you want to use it, open app/Http/kernel.php and register this route middleware by adding it to the routeMiddleware (down below) array:, (*8)
...
'speaks-tongue' => \Pmochine\LaravelTongue\Middleware\TongueSpeaksLocale::class,
...
4: Add in your Env 🔑
APP_DOMAIN=yourdomain.com #Only important for domains with many dots like: '155ad73e.eu.ngrok.io'
SESSION_DOMAIN=.yourdomain.com #Read down below why
Important! Note the dot before the domain name. Now the session is available in every subdomain 🙃. This is important because you want to save all your cookie 🍪 data in one place and not in many other., (*9)
****Note*!** 📝 This step is optional if you use laravel>=5.5 with package auto-discovery feature.
Add service provider to config/app.php in providers section, (*10)
Pmochine\LaravelTongue\ServiceProvider::class,
Usage - (or to make it runnable 🏃♂️)
Locale detection 🔍
Open app/Providers/RouteServiceProvider.php and add this, (*11)
public function boot()
{
// This will guess a locale from the current HTTP request
// and set the application locale.
tongue()->detect();
//If you use Carbon you can set the Locale right here.
\Carbon\Carbon::setLocale(tongue()->current());
parent::boot();
}
...
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-dependent Laravel components (e.g. Translation) as you normally do., (*12)
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 routes/web.php:, (*13)
// 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' => [ 'speaks-tongue' ]], function() {
Route::get('welcome', 'WelcomeController@index');
});
For more information about Middleware, please refer to Laravel docs., (*14)
Frontend 😴
<!doctype html>
<html lang="{{tongue()->current()}}" dir="{{tongue()->leftOrRight()}}">
<head>
@include('layouts.head')
</head>
<body>
...
The above <html> tag will always have a supported locale and directionality (‘ltr’ or ‘rtl’). The latter is important for right-to-left languages like Arabic and Hebrew since the whole page layout will change for those., (*15)
Configuration
Once you have imported the config file, you will find it at config/localization.php., (*16)
Important: Before you start changing the values, you still need to set the "main language" of your page. If your main language is fr, please add this to your config/app.php file under 'fallback_locale' => 'fr',., (*17)
We asume that your fallback language has always translated pages. We get the current locale via four ways:, (*18)
- First we determine the local with the subdomain of the URL the user is coming from
If there is no subdomain added, we get the locale from:, (*19)
- an already set language cookie
- or the browsers prefered language
- or at the end we fall back to the
fallback_locale
Note: The value locale in config/app.php has no impact and is going to overwritten by tongue()->detect(); in app/Providers/RouteServiceProvider.php, (*20)
Configuration values
You don't need to worry about this, only when you are using domains with multiple dots, like: 155ad73e.eu.ngrok.io. Without it, we cannot check what your subdomain is., (*21)
-
beautify_url (default: true)
Makes the URL BEAUTIFUL 💁♀️. ( Use to set fallback language to mydomain.com and not to en.mydomain.com). That is why I even created this package. I just could not find this! 😭, (*22)
Sometimes you would like to have your admin panel as a subdomain URL. Here you can whitelist those subdomains (only important if those URLs are using the middleware)., (*23)
-
aliases (default: [])
Sometimes you would like to specify aliases to use custom subdomains instead of locale codes. For example:
gewinnen.domain.com --> "de"
gagner.domain.com --> "fr",
-
acceptLanguage (default: true)
Use this option to enable or disable the use of the browser 💻 settings during locale detection., (*24)
-
cookie_localization (default: true)
Use this option to enable or disable the use of cookies 🍪 during the locale detection., (*25)
-
cookie_serialize (default: false)
If you have not changed anything in your middleware "EncryptCookies", you don't need to change anything here as well. More, (*26)
-
prevent_redirect (default: false)
Important for debugging, when you want to deactivate the middleware speaks-tongue., (*27)
-
supportedLocales (default: 🇬🇧🇩🇪🇪🇸🇫🇷🇭🇺)
Don't say anyone that I copied it from mcamara 🤫, (*28)
Route translation
If you want to use translated routes (en.yourdomain.com/welcome, fr.yourdomain.com/bienvenue), proceed as follows:, (*29)
First, create language files for the languages that you support:, (*30)
resources/lang/en/routes.php:, (*31)
return [
// route name => route translation
'welcome' => 'welcome',
'user_profile' => 'user/{username}',
];
resources/lang/fr/routes.php:, (*32)
return [
// route name => route translation
'welcome' => 'bienvenue',
'user_profile' => 'utilisateur/{username}',
];
Then, here is how you define translated routes in routes/web.php:, (*33)
Route::group([ 'middleware' => [ 'speaks-tongue' ]], function() {
Route::get(dialect()->interpret('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 interpret() method., (*34)
Helper Functions - (finally something useful 😎)
This package provides useful helper functions that you can use - for example - in your views:, (*35)
Translate your current URL into the given language
<a href="{{ dialect()->current('fr') }}">See the french version</a>
Get all translated URL except the current URL
@foreach (dialect()->translateAll(true) as $locale => $url)
<a href="{{ $url }}">{{ $locale }}</a>
@endforeach
You can pass false as parameter so it won't exclude the current URL., (*36)
Translate URL to the language you want
<a href="{{ dialect()->translate('routes.user_profile', [ 'username' => 'JohnDoe' ], 'fr') }}">See JohnDoe's profile</a>
// Result: https://fr.example.com/utilisateur/JohnDoe
Remember: Set the translation in the lang folder, (*37)
Use dialect()->translate($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., (*38)
You can pass route parameters if necessary. If you don't give a specific locale, it will use the current locale ☺️., (*39)
Redirect URL to the language you want
<a href="{{ dialect()->redirectUrl(route('home'), 'fr') }}">See Homepage in French</a>
// Result: https://fr.example.com
Use dialect()->redirectUrl($url = null, $locale = null); to redirect for example to the same URL but in different locale. Warning: Works only when the paths are not translated. Use dialect()->translate() for that., (*40)
Get your config supported locale list
$collection = tongue()->speaking(); //returns collection
Remember it returns a collection. You can add methods to it (see available methods)
Examples:, (*41)
$keys = tongue()->speaking()->keys()->all(); //['en','de',..]
$sorted = tongue()->speaking()->sort()->all(); //['de','en',..]
Additionally, you can even get some addtional information:, (*42)
tongue()->speaking('BCP47', 'en'); // en-GB
tongue()->speaking('subdomains'); // ['admin']
tongue()->speaking('subdomains', 'admin'); // true
tongue()->speaking('aliases'); // ['gewinnen' => 'de', 'gagner' => 'fr]
tongue()->speaking('aliases', 'gewinnen'); //' de'
Get the current language that is set
$locale = tongue()->current(); //de
Or if you like you can get the full name, the alphabet script, the native name of the language & the regional code., (*43)
$name = tongue()->current('name'); //German
$script = tongue()->current('script'); //Latn
$native = tongue()->current('native'); //Deutsch
$regional = tongue()->current('regional'); //de_DE
## How to Switch Up the Language 🇬🇧->🇩🇪
For example with a selector:, (*44)
<ul>
@foreach(tongue()->speaking()->all() as $localeCode => $properties)
<li>
<a rel="alternate" hreflang="{{ $localeCode }}" href="{{ dialect()->current($localeCode) }}">
{{ $properties['native'] }}
</a>
</li>
@endforeach
</ul>
Or in a controller far far away..., (*45)
/**
* Sets the locale in the app
* @return redirect to previous url
*/
public function store()
{
$locale = request()->validate([
'locale' => 'required|string|size:2'
])['locale'];
return tongue()->speaks($locale)->back();
}
Upgrade Guide 🎢
Upgrade to 2.x.x from 1.x.x
There are little changes that might be important for you., (*46)
- We added two new config elements in localization.
domain and aliases. Add these like here.
- Add
APP_DOMAIN in your .env if you have a complicated domain, like: 155ad73e.eu.ngrok.io
- Now you are able to use aliases in your subdomain. For example:
gewinnen.domain.com --> "de"
- If a subdomain is invalid, it returns to the latest valid locale subdomain.
Support for Laravel 9.x.x
If you want to use:, (*47)
PHP <=8.0 and Laravel 9.x.x, (*48)
you need to download the version 4.0.0., (*49)
composer require pmochine/laravel-tongue:4.0.0
Support for Laravel 7.22.0 up to Laravel 8.41.0
If you want to use:, (*50)
PHP >=7.3 and at least 7.22.0 <= Laravel <=8.41.0, (*51)
you need to download the version 3.0.0., (*52)
composer require pmochine/laravel-tongue:3.0.0
Support for Laravel 6.x.x up to Laravel 7.21.0
If you want to use:, (*53)
PHP >=7.2 and at least 6.x.x <= Laravel <=7.21.0, (*54)
you need to download the version 2.2.1 or lower., (*55)
composer require pmochine/laravel-tongue:2.2.1
Support for Laravel 5.x.x
If you want to use:, (*56)
PHP >=7.0 and at least 5.4 <= Laravel <=5.8, (*57)
you need to download the version 2.0.0 or lower., (*58)
composer require pmochine/laravel-tongue:2.0.0
Security
If you discover any security related issues, please don't email me. I'm afraid 😱. avidofood@protonmail.com, (*59)
Credits
Now comes the best part! 😍
This package is based on, (*60)
- https://github.com/hoyvoy/laravel-subdomain-localization
- https://github.com/mcamara/laravel-localization
Oh come on. You read everything?? If you liked it so far, hit the ⭐️ button to give me a 🤩 face., (*61)
Wallogit.com
