Nova Current Environment Card Laravel Package

Getting Started

The 2.0.0 release adds shipped language files and registers them with Nova via Nova::translations, so the package's UI strings can now be localized instead of hard-coded to English. If you are already using the package, this is mostly a "free" upgrade; if you are installing fresh, this is the first thing to verify after composer require.

Minimal setup:

1. Install and publish, as usual.

   composer require <vendor>/<package>:^2.0
   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
   

   Check whether the publish tags now include a --tag=<package>-translations group. If the package ships resources/lang/{locale}/... under its own namespace, you normally do not need to publish them — only publish if you intend to override strings.

2. Look first at the service provider's boot() method. After 2.0.0 it should call something like:

   Nova::translations(__DIR__.'/../resources/lang');
   

   This is the mechanism that makes __('package::messages.key') resolve inside Nova's Vue components and PHP classes alike. If you maintain a custom fork or a wrapper package, mirror this call — Nova does not auto-discover translation directories outside of its own.

3. Confirm your locale resolves. Set APP_LOCALE=fr (or whatever Nova is running under) and hit a page containing the package's tool/card/field. Strings that previously rendered in English should now render translated. If nothing changes, run php artisan optimize:clear — Nova caches compiled assets and config aggressively.

First meaningful use case: a multi-locale Nova dashboard where one team member works in French and another in English. Before 2.0.0 you would have had to fork the package or override strings via JS; now you set APP_LOCALE per user (or via a SetLocale middleware / Nova user preference) and the package follows along.

Implementation Patterns

Per-user locale in a multi-tenant Nova install. Nova doesn't ship a locale switcher, so the common pattern is a small middleware or a Nova::serving() callback that sets the locale from the authenticated user:

// app/Providers/NovaServiceProvider.php
Nova::serving(function () {
    if ($locale = auth()->user()?->locale) {
        app()->setLocale($locale);
    }
});

Because the package now registers its translations through Nova::translations, this works for both server-rendered labels and the JS side without extra wiring.

Overriding individual strings without forking. Publish the translations and edit only the keys you care about:

php artisan vendor:publish --tag=<package>-translations

Then edit lang/vendor/<package>/{locale}/.... Laravel's translation loader prefers the published copy over the package's, so you keep upstream updates for everything else. Keep overrides in a small, documented directory — they are easy to lose track of during upgrades.

Adding a locale the package doesn't ship. Copy the en directory to your target locale, translate, and place it under the published vendor path. Do not put it inside vendor/ directly; it will vanish on composer install.

Tool/card components that need strings in JS. If the package's Vue components previously hard-coded strings, 2.0.0 typically exposes them via Nova's translation helper:

// In a custom tool extending the package's component
this.__('Package Name::messages.saved')

Use the same namespace the PHP side uses, otherwise you get silent fallbacks to the key itself. Grep node_modules/vendor for Nova::translations to see the exact namespace registered.

Testing. Add a locale assertion to your feature tests so a future release that drops translations fails loudly:

public function test_tool_labels_are_translated(): void
{
    app()->setLocale('fr');
    $this->assertSame('Enregistré', __('<package>::messages.saved'));
}

CI integration tip. If you build Nova assets in CI, ensure the translation files are present before npm run prod, since some packages inline JSON translations at build time. Publish/copy steps must precede asset compilation in your pipeline.

Gotchas and Tips

• The major version bump deserves a changelog read. The release note only describes additive work (language files + Nova::translations), which is unusual for a 2.0.0. A major bump can also signal a raised Nova/PHP minimum, renamed translation keys, or a changed service provider class name. Diff the composer.json constraints before upgrading and run your test suite — translation key renames are silent breakage because __() falls back to the key rather than throwing.
• Nova::translations only affects Nova context. If the package's classes are also used outside Nova (queued jobs, API responses, mail), those paths still need standard loadTranslationsFrom() in your own provider. Don't assume the Nova call covers everything.
• Translation keys render as themselves on miss. A missing key shows up as package::messages.foo in the UI, which is obvious — but a stale key shows an old string, which is not. After upgrading, spot-check the handful of strings that changed.
• Cache clearing is not optional. php artisan optimize:clear (or at minimum config:clear and view:clear) after upgrading and after publishing translations. Nova's own nova:cache / nova:clear-cache commands may also need running if you use Nova's asset caching.
• APP_LOCALE vs. APP_FALLBACK_LOCALE. The package's fallback chain is Laravel's: requested locale → fallback_locale → key. If you set APP_FALLBACK_LOCALE=en and your user is on fr-CA, you'll get fr only if the package ships it; otherwise you silently drop to English. Check which locales are actually shipped before promising coverage to a stakeholder.
• Publishing is copy, not link. Published translation overrides are snapshots. After upgrading the package, diff them against the new upstream files — new keys added in 2.0.0 won't appear in your published copy, and you'll get key-as-string output for those.
• Extension point worth knowing: if you maintain several packages, register all of their translation directories in one Nova::serving()/boot() block rather than scattering calls. It's easier to audit and avoids the class of bug where one package's translations are registered but a second one's aren't.
• Debugging checklist when a string won't translate: (1) is APP_LOCALE set and config:cleared? (2) does the key exist in the package's resources/lang/{locale}? (3) is the namespace registered via Nova::translations or loadTranslationsFrom? (4) is a published override shadowing it? Answering these four in order resolves nearly every case.