Switch Locale Laravel Package

Getting Started

This is a Laravel Nova tool, so the hard prerequisite is a working Nova installation (Laravel 9/10/11 + laravel/nova). Without Nova licensed and installed, there is nothing to switch — the package only adds a UI affordance inside the Nova admin.

Install and register:

composer require day4/switch-locale

Then register the tool in app/Providers/NovaServiceProvider.php inside the tools() method:

use Day4\SwitchLocale\SwitchLocale;

public function tools()
{
    return [
        new SwitchLocale(['en', 'fr', 'nl']),
        // or, if the package reads config: new SwitchLocale,
    ];
}

Check the package src/ first — this is a small, single-purpose tool (1 star, no dependents), so the entire behaviour is usually one Tool class plus a Vue component. Confirm the exact constructor signature there before copying any README snippet; a package this small tends to drift from its docs.

Run php artisan nova:asset day4/switch-locale (or nova:publish) if the toolbar component doesn't appear, then hard-refresh the browser.

First use case: a Nova panel used by non-English admins (support staff, regional ops) where you want each user to pick their interface language without touching .env or redeploying. The switcher lives in the Nova navbar; picking a locale writes to the session (or the user record) and Laravel's app()->setLocale() picks it up on subsequent requests.

Implementation Patterns

Per-user persistence (the pattern worth building). Session-only locale resets on logout and is invisible to background jobs. The durable version is a locale column on users:

// migration
$table->string('locale', 5)->default('en');

// middleware, appended to Nova's middleware stack
public function handle($request, Closure $next)
{
    if ($locale = $request->user()?->locale) {
        app()->setLocale($locale);
    }
    return $next($request);
}

Wire the toolbar's selection back to that column via a small route or a Nova action, rather than relying on whatever storage the tool ships with. This keeps locale consistent across Nova, your public site, and queued mail.

Conditional registration. Don't show a switcher to single-language tenants:

public function tools()
{
    return array_filter([
        count(config('app.supported_locales', ['en'])) > 1
            ? new SwitchLocale(config('app.supported_locales'))
            : null,
    ]);
}

Keep the locale list in one place. Define config/app.supported_locales and feed both the tool and AppServiceProvider's validation from it. Duplicating the array between Nova and the front end is the most common source of "the switcher shows Italian but there are no it translation files" bugs.

Compose with translation packages. If you use spatie/laravel-translatable or nova-translatable, treat the UI locale and the content locale as separate concerns. The switcher changes Nova's chrome (menus, buttons, validation messages); editing a model's title in three languages is handled by the translatable field, not this tool. Users conflate the two constantly — label the switcher clearly.

Local development workflow. Seed a couple of lang/{locale} directories with at least Nova's own translations (vendor/laravel/nova/resources/lang) so you can actually see the switch take effect. A switcher that changes nothing visible looks broken even when it works.

Gotchas and Tips

• Nova-only. There is no Blade directive, no middleware auto-registration for the front end, no route macro. If you also want the public site to honour the choice, write that middleware yourself — this package won't do it.
• Asset caching. After composer require or any version bump, Nova serves stale compiled assets. Run php artisan nova:publish and php artisan view:clear; a "tool doesn't appear" report is almost always this, not a missing registration.
• Config cache. If the tool reads a published config file, php artisan config:cache in production will freeze the locale list. Every deploy that changes supported locales needs a re-cache, or you'll debug a phantom bug for an hour.
• Locale ≠ translation completeness. App::setLocale('de') with no lang/de directory silently falls back to fallback_locale. The switcher will look like it works while nothing changes.
• Middleware ordering. If you add locale middleware to Nova's stack, place it after Authenticate so $request->user() is populated; otherwise you'll fall back to the default locale on every request and blame the package.
• Session driver. SESSION_DRIVER=array (common in some test/CI setups) makes session-persisted locales evaporate between requests. Tests that assert on locale need actingAs() plus a real session driver.
• Bus factor. One star and zero dependents means no community to catch regressions. Pin the version in composer.json ("day4/switch-locale": "1.0.*"), read the Tool class once so you know exactly what it does, and if it fights you, fork it — the whole feature is roughly 150 lines of Tool + Vue component, and a bespoke implementation is usually cheaper than waiting on an upstream fix.
• Extension point. Rather than patching the vendor directory, extend the tool class in app/Nova/ and register your subclass. That survives composer update and lets you add a "reset to default" button or per-user persistence without touching vendor/.