Nova Language Switch Laravel Package

Technical Evaluation

Architecture fit. This is an admin-chrome affordance, not infrastructure. Mechanically it is a Nova tool that renders a locale dropdown in the admin header and writes the selected locale somewhere the request pipeline reads (session by default). It translates nothing itself — it only influences which locale the application resolves on subsequent requests. Fit is therefore conditional on two facts: (1) Laravel Nova is the admin surface of record, and (2) the application actually honors the mechanism the package writes to. If either is false — API-only service, Filament or SPA admin, or a front end that resolves locale from users.locale while the package writes to session — there is no partial-value fallback. Roadmap-wise this belongs under "backoffice ergonomics," not "internationalization," and that framing is the TPM's first deliverable.

Integration feasibility. Mechanically trivial: composer require, service provider auto-discovers, register the tool in NovaServiceProvider::tools(), optionally publish a languages config map. The integration risk is not installation but the source-of-truth decision — session vs. users.locale vs. both — and ensuring the whole pipeline (web middleware, Nova middleware, queues, Octane, shared caches) honors it consistently. That decision, not the package, drives the schedule.

Technical risk.

• Nova version coupling. Nova is licensed and its tool API breaks between majors (v4 → v5). Release 3.0.0 (Jan 2025) adds Nova 5 support, but a 26-star, single-maintainer package is a plausible casualty of the next major. Assume you may fork; budget compatibility review as a recurring line item at each Nova bump.
• Locale bleed. Session- or singleton-scoped locale that is not reset per request can contaminate queued jobs, Octane workers, or cached responses. Highest-severity failure mode and it is silent — wrong-language emails and cached pages, not a stack trace.
• Maintainer concentration. 26 stars, zero dependents, no community backstop. Treat this as ~200 readable lines you are adopting, not a supported dependency.
• Scope ambiguity. The description says "switch language in your application," which undersells that it controls Nova's UI chrome only. Assume-latter-ship-nothing is the trap, and it is a stakeholder-messaging risk as much as a technical one.

Key questions.

1. Does it write session locale, call App::setLocale(), or persist a user column — and which is authoritative on the next request?
2. Is Nova's own UI localized by it, or only the front-end application?
3. What are the Composer constraints on laravel/framework and laravel/nova? Does 3.0.0 properly declare Nova 5?
4. Does it ship middleware, and where must it sit relative to StartSession and the cache middleware?
5. Is locale included in any cache key or Vary header?
6. Can the tool be gated behind a Nova permission?
7. License and maintainer responsiveness — can we fork under our namespace if abandoned?

Integration Approach

Stack fit. Requires Laravel + a paid Nova license + compatible framework constraints, with at least two locales and real translation files behind them. Non-starter for API-only services, SPA/Inertia front ends without server-resolved locale, teams on Filament or another admin panel, and any stack where Nova is not the back office.

Migration path. Additive and reversible. Install, register, pilot in a staging Nova panel. If the persistence model does not match the intended locale source of truth, vendor the tool class into app/Nova/Tools and adapt. For a package this small, forking is a realistic first option rather than a fallback, and it collapses the vendor-risk question in one move — near-zero exit cost is the core argument for proceeding.

Compatibility. Validate the constraint matrix against pinned Laravel and Nova minors before commitment. Critically, validate dependency direction: if the app resolves locale via middleware from users.locale but the package writes to session, the switch will appear to work inside Nova and silently no-op elsewhere. Confirm the configured language map maps to locales the app actually ships strings for — a dropdown full of untranslated codes is worse than no dropdown.

Sequencing.

1. Decide and document the locale source of truth (session, user column, or both) — this gates everything downstream.
2. Confirm or implement the middleware that applies locale, and reset it in queued jobs and Octane workers.
3. Integrate the package (or fork) against that mechanism.
4. Add a smoke test asserting end-to-end locale resolution for at least two locales, plus an Octane-specific leakage test.
5. Gate the tool behind a Nova permission, then roll to production as a scoped pilot with the admin team.

Operational Impact

Maintenance. Low ongoing effort, non-zero ownership risk. Budget a compatibility review at every Nova and Laravel major, and name an internal owner up front. Because upstream adoption is thin, the operative question is not "will the maintainer patch it" but "who on our side reads the ~200 lines when it breaks." A fork under an internal namespace is the durable posture.

Support. No vendor support, no SLA, will not clear enterprise procurement gates on its own. The dominant internal ticket will be user confusion: an admin flips language and expects content to change when only UI chrome does. A one-line tooltip ("changes interface language, not content") removes most of it, and a short note in the admin onboarding doc removes the rest. Ramp-up is under a day for a Laravel/Nova-fluent engineer — roughly half of that is the locale-source decision, not the package.

Scaling. Negligible compute — one session write per switch. Correctness, not throughput, is the scaling risk: under Octane or long-running workers a leaked locale contaminates subsequent requests; under shared caches, locale-variant responses must be keyed or varied correctly. With horizontally scaled sessions, a session-backed preference is only as durable as the session store — pin to Redis or persist to the user record if persistence matters.

Failure modes.

1. Locale bleed across requests/workers → wrong-language emails and cached pages (silent, highest severity).
2. Nova major upgrade breaks tool registration with a hard error in the admin panel.
3. Silent no-op — UI flips, front end ignores the value, because persistence does not match locale resolution.
4. Session loss drops an admin back to the default locale, prompting "the switch is broken" reports.

All four are detectable with one integration test plus one Octane test — cheap insurance at this size, and the TPM's ask to engineering should be exactly that: a gated pilot, two tests, and a documented locale source of truth, rather than a blanket rollout.