cosnavel/laravel-query-localization

Query String Localization Package for Laravel

0.3.0 2022-02-09 16:08 UTC

Requires

• php: ^8.0
• illuminate/contracts: ^8.73 || ^9.0
• spatie/laravel-package-tools: ^1.11

Requires (Dev)

• brianium/paratest: ^6.2
• livewire/livewire: ^2.10
• nunomaduro/collision: ^5.3 || ^6.1
• orchestra/testbench: ^6.23 || ^7.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^9.3
• spatie/laravel-ray: ^1.23
• vimeo/psalm: ^4.8

MIT

• Cosnavel

• laravel
• Cosnavel
• laravel-query-localization

README

Query String Localization Package for Laravel

Use this package to localize your laravel application via query strings easily.

Features:

• Localization based on a query string.
• Includes a Livewire language selector component.
• Optionally stores the user language preference to the user's table and apply it for every session.

Installation

To get started, require the package via composer:

composer require cosnavel/laravel-query-localization

Config File

You can publish the config file with:

php artisan vendor:publish --provider="Cosnavel\LaravelQueryLocalization\LaravelQueryLocalizationServiceProvider" --tag="laravel-query-localization-config"

After publishing, config query-localization.php will be created.

The configuration options are:

• supportedLocales Languages of your app (Default: English & German).

• useAcceptLanguageHeader If true, then automatically detect language from browser.

• useUserLanguagePreference If true, save the language preference of an authenticated user in the database and apply the preference on each session

Usage

Register Middleware

To get started, register the LocaleFromQuery middleware for the Route Group that needs to be localized.

// routes/web.php


Route::middleware(LocaleFromQuery::class)->group(function () {
    Route::view('/', 'welcome');
});

User Language Preference

If you want to save the language preference to the users table:

• publish the config file
• enable useLanguageUserPreference in the config file
• publish and run the migrations

You can publish and run the migrations with:

php artisan vendor:publish --provider="Cosnavel\LaravelQueryLocalization\LaravelQueryLocalizationServiceProvider" --tag="query-localization-migrations"
php artisan migrate

• if you want to use mass assignment for the language_preference field in the users table make the field fillable in the user model

Helpers

Get Supported Locales

Return all supported locales and their properties as an array.

Cosnavel\LaravelQueryLocalization\Facades\LaravelQueryLocalization::getSupportedLocales();

Get Current Locale

Return the key of the current locale.

• Return the current locale from the session
• if none found, it negotiates locale from acceptLanguageHeaders.
• when acceptLanguageHeaders option is disabled, and no value is available in the session, use the applications default locale

Cosnavel\LaravelQueryLocalization\Facades\LaravelQueryLocalization::getCurrentLocale();

Determine Valid Locales

Checks if the passed locale is a supportedLocale (check the config to add your needed locales). If it is not, the returned locale is the application's default locale.

Cosnavel\LaravelQueryLocalization\Facades\LaravelQueryLocalization::determineValidLanguage('en');

Set Locale

Set locale programmatically. Internally the passed locale gets determined if it's a valid locale.

Cosnavel\LaravelQueryLocalization\Facades\LaravelQueryLocalization::setLocale('en');

Set User Language Preference

Set an authed user's language preference. The passed language will also be checked for availability.

Cosnavel\LaravelQueryLocalization\Facades\LaravelQueryLocalization::setUserLanguagePreference('en');

Language Selector

If you're supporting multiple locales in your project, you will probably want to provide the users with a way to change the language.

Included in this package is a language selector. The Language Selector is built with Tailwind, Alpine & Livewire.

CleanShot.2021-08-06.at.11.32.42.mp4

Alpine

The Language Picker requires Alpine. You can use the official CDN to quickly include Alpine:

<!-- Alpine v2 -->
<script src="https://cdn.jsdelivr.net/gh/alpinejs/alpine@v2.x.x/dist/alpine.min.js" defer></script>

<!-- Alpine v3 -->
<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>

Usage

Just include the Livewire Component in your blade view. All available locales from your config will be used.

@livewire('language-selector')

When useUserLanguagePreference is enabled, the language preference of an authenticated user will be set.

If you don't want to use Tailwind or want to customize the language picker, I recommend that you publish the component the markup as you like.

php artisan vendor:publish --provider="Cosnavel\LaravelQueryLocalization\LaravelQueryLocalizationServiceProvider" --tag="query-localization-views"

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Credits

• Cosnavel
• Rheamars
• Lotti Thanks for the artwork
• All Contributors

License

The MIT License (MIT). Please see License File for more information.