Looking to hire Laravel developers? Try LaraJobs

laravel-localization maintained by itmosoft

Description
Locale registry, persistent subject preferences, and request locale resolution middleware for Laravel applications.
Last update
2026/11/17 09:26 (dev-main)
License
Links
Downloads
2

Comments
comments powered by Disqus

ITMOSOFT Laravel Localization

Locale registry, persistent per-model locale preferences, and request locale resolution middleware for Laravel 12 and 13.

Requirements

  • PHP 8.3+
  • Laravel 12 or 13

Installation

composer require itmosoft/laravel-localization
php artisan vendor:publish --tag=itmosoft-localization-config
php artisan migrate

The service provider is auto-discovered.

Configuration

Publish config/localization.php to define supported locales, fallback locale, and resolution behavior.

return [
    'supported_locales' => ['en', 'ur', 'ar'],
    'fallback_locale' => 'en',
    'tables' => [
        'preferences' => 'locale_preferences',
    ],
    'middleware' => [
        'route_parameter' => 'locale',
        'use_authenticated_preference' => true,
        'use_accept_language' => true,
    ],
];

Locale registry

use ItmoSoft\Localization\Facades\Localization;

Localization::supported(); // ['en', 'ur', 'ar']
Localization::isSupported('ur'); // true
Localization::fallback(); // 'en'

Persist a subject preference

The package stores preferences against any Eloquent model using a polymorphic identity.

Localization::setPreference($user, 'ur');

Localization::preferenceFor($user); // 'ur'

Localization::forgetPreference($user);

The configured locale must be supported; unsupported values throw InvalidArgumentException.

Request middleware

Register \ItmoSoft\Localization\Http\Middleware\SetRequestLocale::class in your application's middleware stack or route group.

Resolution order:

  1. Supported route parameter configured by middleware.route_parameter.
  2. Authenticated user's persisted locale preference, when enabled.
  3. Best supported match from the Accept-Language request header, when enabled.
  4. Configured fallback locale.

The middleware sets Laravel's application locale for the duration of the request and calls the next middleware. It does not redirect, rewrite URLs, or persist a preference from request input.

Example route:

Route::middleware(\ItmoSoft\Localization\Http\Middleware\SetRequestLocale::class)
    ->group(function () {
        Route::get('/{locale}/account', fn () => view('account'));
    });

Ensure the route parameter name matches middleware.route_parameter.

API

Method Description
supported(): array List configured supported locale codes
isSupported(string $locale): bool Check a locale code
fallback(): string Get configured fallback
setPreference(Model $subject, string $locale): void Store a subject preference
preferenceFor(Model $subject): ?string Read a subject preference
forgetPreference(Model $subject): void Delete a subject preference
resolve(?Request $request = null): string Resolve locale using configured precedence
set(string $locale): void Set the Laravel application locale after validation

Important notes

  • This package manages locale selection and preferences; Laravel's translation and pluralization systems remain responsible for translating content.
  • It does not translate strings, generate translation files, translate database content, or provide RTL layout/CSS.
  • Accept-Language matching uses locale codes and base-language matching, not a full RFC 4647 language negotiation implementation.
  • Locale preferences are stored by polymorphic model type and key.
  • Do not trust arbitrary locale values from user input; only configured locales are accepted.

Testing

composer install
composer test

License

MIT. See LICENSE.