Localizer Laravel Package

Getting Started

Install and publish the config. Require the package with Composer and publish its config/assets; expect a config/localizer.php (or similarly named) file where supported locales, fallback, and persistence settings live.

composer require terranet/localizer
php artisan vendor:publish --provider="Terranet\\Localizer\\LocalizerServiceProvider"

Laravel 5.5+ auto-discovers the service provider; on older versions register Terranet\Localizer\LocalizerServiceProvider in config/app.php manually.

Look here first, in order:

1. src/ — the facade/helper class and any middleware. This package has almost no public documentation and one star, so the source is the docs.
2. config/localizer.php — the real contract: locale list, fallback, session/cookie key names, middleware registration.
3. Any README.md — likely minimal; treat config and source as authoritative.

First use case: switch locale and persist it. The canonical day-one task is a language switcher that sets the app locale, stores it, and redirects back:

// routes/web.php
Route::get('locale/{locale}', function ($locale) {
    app('localizer')->setLocale($locale); // verify exact method in src
    return back();
})->name('locale.switch');

Register the middleware (typically a LocalizerMiddleware that reads the persisted locale and calls App::setLocale()). Add it to the web group in app/Http/Kernel.php; without it, the locale will not follow requests.

Sanity check: if setLocale() does not exist, grep for public function in src/ — the class likely exposes setLocale, getLocale, setDefault, isRTL, or similar.

Implementation Patterns

Facade/helper for locale access. Prefer a single accessor throughout your app rather than scattering App::getLocale() and App::setLocale(), so the persistence logic (session/cookie) stays in one place:

$current = localizer()->getLocale();
localizer()->setLocale($request->user()->locale);

Middleware-driven detection. A common pattern is a middleware that resolves locale in priority order: explicit route parameter → authenticated user's preference → session/cookie → Accept-Language header → config('app.fallback_locale'). Wire the package's middleware into this chain rather than duplicating logic.

Route localization. If the package provides translated route helpers, define routes once and let it generate locale-prefixed URLs (/en/about, /ro/despre). If it does not, pair it with mcamara/laravel-localization for routing and keep this package only for locale state — do not force one tool to do both.

Blade/inertia integration. Expose the current locale and available locales to views via a view composer or shared Inertia prop so switchers render consistently:

View::share('locales', config('localizer.locales'));

Model-level translation (if supported). If the package ships a translatable trait, apply it to models whose attributes vary per locale and store JSON columns. Confirm the storage format against src/ before migrating data — packages differ between JSON columns and side tables.

Queue and console parity. Wrap job dispatch in a locale-setting helper so emails/notifications render in the recipient's language, not the worker's default.

Gotchas and Tips

Unmaintained — pin your Laravel version. Last release was 2021-09-22. On Laravel 10/11 expect deprecations or hard failures (container bindings, Str/Arr helpers, typed properties). Test on a throwaway branch before adopting; if it breaks, vendor the class into app/Support — it is small enough.

Almost no docs, one star, zero dependents. Treat every method signature as unverified. Read src/ fully before writing integration code; do not assume an API from the name.

Config caching. After publishing or editing config, run php artisan config:clear. A stale cached config will silently ignore new locales — a classic "switcher does nothing" cause.

Persistence mismatch. Session-based persistence breaks for API/stateless requests and guests with cookies disabled. Decide explicitly between session, cookie, and user-column persistence, and make the middleware's resolution order deterministic.

Locale does not propagate automatically. App::setLocale() is request-scoped. Queued jobs, scheduled tasks, and artisan commands start at fallback_locale; set locale explicitly inside them or messages go out in the wrong language.

Route caching. If you localize routes, php artisan route:cache can freeze generated URLs. Clear route cache after changing the locale list, and test that route('...', ['locale' => 'ro']) still resolves.

Fallback surprises. Laravel falls back to fallback_locale per missing key, producing mixed-language pages. Keep translation files complete or add a CI check that diffs keys across locale files.

Missing translations are silent. Set app.debug and consider a logging translation loader in dev so untranslated keys surface instead of rendering raw keys to users.

RTL. If the package exposes an isRTL()-style helper, drive dir="rtl" and CSS logical properties from it rather than hardcoding per-locale conditionals.

Alternatives worth benchmarking: mcamara/laravel-localization (routing), spatie/laravel-translation-loader (DB-backed strings), astrotomic/laravel-translatable (model attributes). Given this package's maturity, it is often cheaper to compose those than to maintain a one-star dependency.