Search by

itmosoft / laravel-localization

adeelrao007

Locale registry, persistent subject preferences, and request locale resolution middleware for Laravel applications.

Package info

github.com/ITMOSOFT/laravel-localization

pkg:composer/itmosoft/laravel-localization

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.1 2026-11-17 08:22 UTC

This package is auto-updated.

Last update: 2026-11-17 08:26:58 UTC


README

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.