Nova Language Switch Laravel Package

Product Decisions This Supports

• Admin-localization roadmap sequencing. If multilingual support is anywhere on the roadmap, this package answers a narrow but visible question early: can regional ops, support agents, and content editors work inside the Nova backoffice in their own language without us commissioning a custom tool? It unblocks admin-side localization independently of frontend/content i18n, so it can ship in a sprint or two rather than waiting behind a multi-quarter localization programme. File it under "backoffice ergonomics," not "internationalization."

• Build vs. buy for a small piece of admin chrome. This is a clean, low-stakes version of that call. The package is a Nova tool that renders a locale dropdown and writes the choice to the session — roughly 200 readable lines. Options are (a) Composer dependency, (b) vendor the tool class into app/Nova/Tools, or (c) write it ourselves with a SetLocale middleware (~1 day, most of it the locale-source decision, not the code). All three are cheap and reversible, so the decision should be made in an afternoon, not a steering committee.

• Feature scoping and expectation management. The package switches the Nova interface locale only. It does not translate content models, and it does not touch the customer-facing app. Locking that definition down before development starts prevents the single most expensive misread of this initiative — a stakeholder hearing "we shipped multilingual" when we shipped a dropdown. This is the decision this package most directly informs.

• Locale source-of-truth decision (the actual product decision). Session-scoped locale is fine for admin UX but resets on logout and is per-browser; a persisted users.locale column is durable but requires a migration, a login hook, and middleware. The package gives us session behavior out of the box, so adopting it is implicitly a decision to defer per-user persistence — a defensible MVP stance as long as we say so out loud and track it as a follow-on item rather than discovering it via bug report.

• Dependency and vendor posture. 26 stars, zero dependents, single maintainer, releases that track Nova majors (3.0.0, Jan 2025, adds Nova 5 support). That profile supports a pilot-and-fork-if-needed posture, not standardization. Blast radius is contained: it sits behind the admin login and can be removed in a single release. Adopt it as a starting point with fork cost budgeted as part of the decision.

• Use cases worth validating it against: multi-locale content authoring in Nova; QA and translation verification (flipping locales to eyeball rendered copy); onboarding regional admin teams into a shared backoffice without building a bespoke settings screen; giving non-English-speaking operators a first-class experience in the tool they live in all day.

• Explicitly out of scope for this decision: customer-facing localization, durable per-user locale preferences, locale-aware routing, translated content models, and anything outside the Nova panel. Those are separate roadmap items with separate owners and separate budgets — say so in the ticket.

• What "success" looks like (define before shipping): adoption among non-English-speaking admins, a measurable drop in admin support questions about language, and zero locale-bleed incidents in queues, cached responses, or Octane workers. That last one is the metric that matters — it's a silent failure mode, not a stack trace.

When to Consider This Package

Adopt it when:

• Laravel Nova is your admin surface of record. Nova is a paid, licensed product, so the addressable base is narrow by definition — this package is meaningless without it. If you're on Filament, an SPA admin, or API-only, stop here.
• The application is genuinely multilingual and you want a zero-configuration switcher in the Nova chrome rather than a custom tool plus middleware.
• Session-scoped locale is an acceptable MVP model. Fine for admin UX; not fine if you've promised per-user preferences or locale-aware routing.
• You can live with a small, readable, single-maintainer package and are prepared to fork it. The whole source is reviewable in an afternoon — treat it as code you're adopting, not a supported dependency.
• Version compatibility checks out. 3.0.0 targets Nova 5; the package claims Nova 4+. Verify against your pinned Nova and Laravel minors before you commit, and map the supported-locale config to locales you actually ship translations for.

Look elsewhere, or build it yourself, when:

• You need frontend or content localization. This is a Nova-only admin affordance. Pair it with your existing translation stack (spatie/laravel-translatable, mcamara/laravel-localization) rather than expecting coverage of the storefront.
• Procurement or security review is in the path. A 26-star, single-maintainer package will not clear enterprise gates requiring support SLAs or vendor guarantees. Forking into an internal namespace is the realistic way through, and if you're forking anyway, evaluate whether to just write it.
• You need persisted per-user locale or locale-aware routing out of the box. That's custom work either way, and once you're writing migrations and middleware, the package's value shrinks to a UI affordance.
• Locale correctness at scale is a hard requirement and you can't invest in guardrails. Per-request locale reset, cache keying, and an Octane leakage test are testing obligations the package does not discharge. If nobody owns that work, don't ship the switcher.
• Your locale resolution lives in users.locale via middleware but the package writes to session. You'll get a silent no-op: the switch appears to work inside Nova and does nothing on the front end. Verify the direction of the dependency first.

How to Pitch It (Stakeholders)

For executives (30 seconds): This is a free, small add-on for our admin panel that lets staff switch the backoffice interface language with one click. Cost is effectively zero — no procurement, no license — and the risk is contained because it sits behind the admin login and can be removed in a single release if it disappoints. The payoff is modest but real: regional and non-English-speaking operators stop working in a second language, which reduces admin error rates and shortens onboarding. It changes the interface language, not our content and not our customer-facing site. Treat it as a tactical admin-UX improvement with a measurable adoption signal, not as a strategic localization platform — and expect to revisit the durable per-user preference as a follow-on if adoption justifies it.

For engineering (the ask): A single Composer dependency that registers a Nova tool exposing a locale switcher and stores the choice in the session. Three things to confirm before adoption: (1) compatibility with our pinned Nova and Laravel majors — 3.0.0 adds Nova 5 support and the package claims Nova 4+; (2) that session-scoped locale matches the behavior we want, and if not, where we persist it instead (users.locale plus a login hook) — the locale source-of-truth decision, not the package, is the schedule driver; (3) that it plays nicely with our existing translation middleware, and that locale is reset per request so it can't bleed across Octane workers or queued jobs, and is keyed or varied correctly in shared caches. Surface area is tiny, so the review is short.

Recommended path: a scoped pilot gated behind a Nova tool permission, with one end-to-end locale smoke test across two locales and one Octane-specific leakage test — rather than a blanket rollout. Fallback if the persistence model doesn't fit is a custom Nova tool plus SetLocale middleware, roughly a day, most of it the locale-source decision. Budget a compatibility review at every Nova and Laravel major, name an internal owner for the ~200 lines, and accept that the dominant support ticket will be user confusion between interface language and content language — a one-line tooltip ("changes interface language, not content") removes most of it.