Translations Laravel Package

Getting Started

This is a Filament plugin from the Backstage PHP ecosystem that surfaces translation management inside the admin panel — typically a page/resource for browsing and editing language lines without touching lang/*.php by hand. With zero stars and zero dependents it's effectively unproven in the wild, so treat the source as the primary documentation.

Minimal steps to get a first read on it:

1. composer require backstage/translations in a Laravel app that already runs Filament v3 (check composer.json of the package for the Filament constraint — this is the single most common upgrade breaker).
2. Publish any package config/assets: php artisan vendor:publish --provider="Backstage\Translations\TranslationsServiceProvider" (if no tag is documented, run vendor:publish interactively and look for the package's entries).
3. Register the plugin on your panel in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(\Backstage\Translations\TranslationsPlugin::make());
   }
   

   Confirm the actual class via composer dump-autoload -o and a namespace scan, since Backstage packages have historically changed namespace casing between releases.
4. Log into /admin and look for the translations entry in the nav.

Where to look first: vendor/backstage/translations/src/ — specifically the Plugin/ServiceProvider and any Resources/ or Pages/ directory. That tells you in ~2 minutes whether it edits DB-backed translations, rewrites files on disk, or both. That distinction drives every downstream decision.

First use case: point it at a single locale in a non-production environment and edit one key. Verify what changed on disk (or in the DB) before trusting it with a full translation set.

Implementation Patterns

Treat it as an editor layer, not a source of truth. The healthy pattern is: keep committed lang/*.php files as canonical, use the package UI for review/edit cycles, and diff the output before commit. If the package writes files directly, wrap edits in a review step; if it uses a DB-backed loader, back it with periodic export.

Per-panel scoping. Mount the plugin only on the admin panel, not on tenant or customer-facing panels:

->plugin(
    TranslationsPlugin::make()
        ->visible(fn () => auth()->user()?->can('manage-translations'))
)

Filament plugin objects usually expose canAccess() / visible() on the owning page — check the source for the exact hook name.

Pair with role gates. Translation editing is effectively content injection into your UI. Gate it behind a dedicated permission rather than letting every panel user in:

Gate::define('manage-translations', fn (User $u) => $u->hasRole('admin'));

Workflow integration for teams:

• Run the edit pass on a scratch branch.
• git diff lang/ (or dump the DB table) as the review artifact.
• CI job that lints lang/*.php for syntax validity — a broken language file takes down every page that calls __().

Multi-locale rollout. Load only the locales you actually support into the UI. Most such plugins iterate every lang/ subdirectory; dropping a stray lang/vendor/ or a half-finished locale directory into the folder creates noise and risks partial writes.

Pair with Filament's own locale switcher so you can preview the edit in-context (->userMenuItems()... with app()->setLocale()), rather than trusting the raw string.

Gotchas and Tips

• Filament version drift is the biggest risk. With no dependents there is no compatibility signal. Pin the package and test on a throwaway branch against your exact Filament minor before adopting.
• Namespace guesses will bite you. Backstage\Translations\... vs Backstage\TranslationsFilament\... — always confirm from the autoload mapping in vendor/backstage/translations/composer.json.
• File-writing vs DB-backed. If it rewrites lang/*.php, check: does it preserve comments? Does it escape quotes and backslashes correctly? Does it touch files owned by other packages (under lang/vendor/)? Test with a string containing ', \n, and {{ }} before letting anyone else use it.
• Permissions default is often "any authenticated panel user." Add an explicit gate on day one.
• Caching. If translations go through spatie/laravel-translation-loader or Filament's own cache, edits may not appear until php artisan cache:clear / php artisan optimize:clear. Document that for editors, otherwise you'll get "it doesn't save" tickets.
• Debugging a blank or missing page: check php artisan filament:about (or the panel's plugin list) to confirm registration, then storage/logs/laravel.log — a throwing resource often renders as a silent 404 in Filament.
• Extension points to inspect in src/: the plugin's fluent setters (usually ->navigationGroup(), ->navigationLabel(), ->slug()), the Resource form() schema if you need extra fields (context, plural variants), and any events fired on save — those are your hooks for validation or audit logging.
• Don't let it be the only copy. Whatever happens, keep canonical translations in version control. A zero-dependency package with an unpublished API is not the place to store your only copy of production copy text.
• Budget an afternoon to read the source. At this adoption level that's cheaper than discovering its behavior through incidents, and it's the honest cost of a package nobody else has vetted.