Filament Translatable Laravel Package

Getting Started

• Install with composer require filamerce/filament-translatable. The package is a Filament panel plugin that adds locale switching on top of spatie/laravel-translatable-style models.
• This release (v3.2.0) is the first line compatible with Filament v5. Before you composer require, confirm your Filament major version. On Filament v3/v4, pin to a pre-3.2 tag; on Filament v5, you need 3.2.0+.
• Register the plugin in each panel you want it on, in app/Providers/Filament/*PanelProvider.php, inside the panel() closure (->plugin(...)). A language switcher (usually in the topbar/user menu) and per-locale field switching are the first things to verify after php artisan filament:optimize-clear.
• First realistic use case: a Post model whose title/body are stored as JSON with a Translatable trait. Open the edit page, switch locale in the topbar, and confirm the form fields swap to that locale's values rather than overwriting the current locale.
• Look first at: the package README's panel-registration snippet, the published config (if any) for locales/fallback_locale, and your model's $translatable array — the three must agree on locale keys.

Implementation Patterns

• Panel-level, not per-resource. Add the plugin once per panel; the locale switcher is global. If you have multiple panels (admin vs. customer), register it in each and be deliberate about default locale per panel.
• Pair with spatie/laravel-translatable on the model and JSON columns in the migration. The switcher is only useful if the fields underneath are actually translatable; otherwise switching does nothing visible.
• Scope the switcher to relevant pages. If some resources aren't translatable, consider a separate translatable-only panel or conditional visibility, so editors don't context-switch on pages where locale is irrelevant.
• Header actions / custom pages: reuse the current locale in your own closures (app()->getLocale() vs. the panel's selected locale) so custom actions read/write the same translation the user is editing.
• Seed/factory + tests: set the panel locale explicitly in feature tests (Livewire test helpers) and assert the correct JSON key was written — this catches the classic "wrote to en while viewing fr" bug. Livewire + Filament tests are the fastest way to regress-check a Filament major bump.
• Upgrade path from v3.1.x → v3.2.0: bump Filament to v5 first, then the package, then run the full Filament test suite. Do this on a branch; Filament majors routinely change panel-provider APIs and asset/build assumptions, and v3.2.0's only functional change is that compatibility.

Gotchas and Tips

• The big one: Filament v5 compatibility is the entire functional change in v3.2.0. The rest of the changelog is Dependabot (git-auto-commit-action 6→7, actions/checkout 5→6, fetch-metadata 2.4→2.5) — CI hygiene, not runtime. Treat this release as a compatibility bump, not a feature drop.
• Don't upgrade the package without upgrading Filament. v3.2.0 targeting v5 while your app is on v4 will surface as obscure plugin/service-provider resolution errors or a missing switcher, not a clean Composer conflict.
• Locale key ≠ app()->getLocale(). The panel's selected locale and the application locale can diverge; code that writes app()->getLocale() in an action can silently hit the wrong JSON key. Prefer whatever the package exposes for the active locale, or set them consistently.
• Fallback locale display can look like a bug. With spatie's fallback enabled, an empty translation for the current locale renders the fallback value — this is expected, but editors report it as "not saving." Document it, and check the raw JSON column when debugging.
• Clear Filament caches after upgrade: php artisan filament:optimize-clear (and view:clear/config:clear if you publish config). Stale component caches are the usual cause of "the switcher disappeared after upgrading."
• Extension points: if the package's switcher doesn't match your design, prefer overriding the render hook / registering your own panel render hook over forking; a fork will make the next Filament major bump your problem. Keep the plugin registration thin so swapping or removing it is a one-line change.
• Pin versions in composer.json (e.g. ^3.2) and note the Filament constraint in your README/AGENTS docs — this package's version tracks Filament's major, so future readers need that coupling spelled out.