Laravel Nova Translation Manager Laravel Package

Getting Started

Install and register

composer require voicecode/laravel-nova-translation-manager

Nova tools generally register one of two ways — check which this package uses before assuming:

1. Auto-registration via a service provider discovered by Laravel (look in the package's src/ for a *ServiceProvider.php with tools() or Nova::tools()).
2. Manual registration in app/Providers/NovaServiceProvider.php:

public function tools()
{
    return [
        new \Voicecode\TranslationManager\TranslationManager(),
        // ...existing tools
    ];
}

First places to look after install

• config/ inside the package — publish it if a tag exists (php artisan vendor:publish --provider="Voicecode\...\ServiceProvider"). This usually controls the paths it scans and the locales it offers.
• The package README.md — this repo has almost no signal (0 stars, 0 dependents, no score), so the README and the source are your only source of truth.
• Your lang/ (Laravel 9+) or resources/lang/ (Laravel 8 and earlier) directory — that's what the tool will read and write.

First use case

Open Nova → Translations. The highest-value first action is not editing a string — it's running a coverage pass: open a locale side-by-side against your source locale (usually en) and find keys that exist in one but not the other. That audit is the reason to install a translation manager at all; day-to-day string edits can be done in the UI, but they can also be done in an editor, whereas cross-locale parity is painful by hand.

Before touching anything in production, point the tool at a non-production environment, confirm where it writes, and commit the current lang/ directory so you can diff and revert.

Implementation Patterns

Treat files (or DB) as the source of truth, and pick one

Most managers of this type either write back to lang/*.php / lang/*.json files or persist to a database table with a loader. Decide which mode this package uses before building a workflow around it:

• File-backed: the Nova UI is just a nicer editor over lang/. Git remains canonical. Merges, PRs, and deploys work normally.
• DB-backed: you need a loader (e.g. spatie/laravel-translation-loader) in the request path, plus a sync/export command to get translations back into files or a seed. Without that, developers editing lang/ will silently see stale strings.

Daily developer loop

1. Write feature code with __('messages.new_key') as usual.
2. Open the Nova tool, filter by the file/group, add the key for every active locale.
3. Commit the resulting lang/ changes alongside the feature branch so the translation diff lands in the same PR.

This keeps translators and developers from stepping on each other: developers own key creation, translators own value editing, and both see the same file in review.

Locale onboarding

When adding a locale (say de), don't hand-create the file. Use the tool to duplicate/clone from en (if supported) or create the file empty and use the missing-key view to fill it. This is where the manager earns its keep — it turns "add German" from an afternoon of copy-paste into a checklist.

Translator handoff

If translators are non-developers, give them a Nova account with a policy that grants access only to the translations tool and nothing else. If you can't or won't, export the missing keys as CSV/JSON (if the package supports it) and re-import — otherwise skip the tool for handoff and use a dedicated TMS.

Guarding against regressions

Add a small test or artisan command that asserts parity between en and each shipped locale:

// tests/Feature/TranslationParityTest.php
foreach (config('app.available_locales') as $locale) {
    // assert every key in lang/en exists in lang/{$locale}
}

The Nova tool is an editor; it isn't CI. A parity test catches the case where someone edits in the UI on staging and forgets to commit.

Permissions

Nova tools respect Gate/policies if the tool checks them. Verify by logging in as a non-admin and confirming the tool is hidden or read-only. Don't assume — a translation manager that writes files is effectively a code-deployment surface, and you don't want every Nova user with it.

Gotchas and Tips

Caches will lie to you. After editing translations, if strings don't change: php artisan config:clear && php artisan cache:clear && php artisan view:clear. If you use spatie/laravel-translation-loader or laravel-translation-cache, clear that too. A stale translation cache is the single most common "the tool is broken" report.

File permissions. File-backed managers need the web process to be able to write to lang/ (or resources/lang/). On production that's usually a bad idea — either make it read-only there and edit in staging, or ensure the directory is owned correctly and excluded from deployment overwrites. Never grant write access casually; it's a remote code execution vector if the tool is reachable by an untrusted user.

JSON vs PHP files. Laravel supports both lang/en.json (flat keys, e.g. "Hello") and lang/en/messages.php (nested arrays). Many tools handle one well and the other poorly. Confirm which your project uses and test the tool against a nested file with dotted keys ('nav' => ['home' => 'Home']) before relying on it.

Nested keys and dots. A key like messages.welcome.title maps to three levels of array. Editing a nested key in a UI often flattens or re-nests it, producing diffs that look like whole-file rewrites. Review the git diff after the first few edits to confirm the tool preserves structure and ordering.

Git conflicts. Two people editing different keys in the same file will still conflict if the tool rewrites the whole file. Prefer one editor at a time per file, or serialize translation changes through a single PR. Alphabetical re-sorting by the tool makes conflicts worse — check whether sorting is configurable.

Laravel/Nova version compatibility. This package has essentially no ecosystem footprint (0 stars, 0 dependents, unrated). Verify it supports your Nova major version (Nova 4 vs 5 differ in tool registration and frontend assets) and your Laravel version's lang directory layout. If the README doesn't state compatibility, read composer.json's require block — that's the real answer.

Maintenance risk. With zero dependents and a blank score, assume no upstream support. Pin the exact version in composer.json, read the source before installing (it's small — a Nova tool plus a service provider), and be prepared to fork it. The core logic — list files, parse arrays, write back — is not hard to reimplement if the package rots. For a translation manager specifically, weigh it against just using an editor plus a parity test; the tool has to save you more time than it costs.

Debugging. If the tool loads blank or errors on save, open the browser network tab and inspect the API call the tool makes — Nova tools are Vue components hitting your app's routes, so the failing request usually names the exact path or locale it can't find. Cross-check against the config's configured paths and the actual on-disk directory names.

Extension points. Look for a published config (paths, locales, excluded groups), publishable views (to relabel or trim UI), and any artisan commands. If the package exposes a "sync" or "import/export" command, wire it into your deploy or CI pipeline rather than clicking the UI — reproducible is better than manual for anything touching lang/.