Filament Translation Manager Laravel Package

Getting Started

This is the first release of the package in the 3.x line and the first compatible with Filament 5.x. Treat 3.0.0 as a version-alignment major: the headline change is the Filament constraint, so the upgrade path is really "upgrade Filament, then upgrade this package."

1. Check your Filament version first. Run composer show filament/filament and confirm you are on 5.x. If you are still on Filament 4.x, stay on the 2.x line of this package — 3.0.0 will not install alongside it.
2. Require the package with an explicit constraint (composer require vendor/package:^3.0) so you don't accidentally resolve back to a 2.x release on an older panel.
3. Run the upgrade chores after install: php artisan filament:upgrade, then php artisan optimize:clear. Filament caches component/asset manifests and stale entries are the most common cause of "the plugin installed but nothing appears."
4. Publish and inspect the config (php artisan vendor:publish --tag=...) before writing any code. Reading the config file is the fastest way to understand what the package actually exposes — options, defaults, and feature toggles are usually more revealing than the README.
5. Where to look first: the package's service provider (to see what it binds and which Filament hooks it registers) and any src/Filament/ directory (resources, pages, widgets, actions). Those two locations tell you whether this is a turnkey plugin or a toolkit you compose into your own panel.
6. First use case: register the plugin on a single non-production panel, load it, and confirm the expected navigation items/pages render. Do this before wiring it into every panel — plugin registration is per-panel in Filament 5, and a plugin that behaves on one panel may collide with another's navigation or tenancy setup.

Implementation Patterns

Register at the panel level, not globally. The idiomatic Filament 5 pattern is ->plugin(YourPlugin::make()) inside a PanelProvider::panel() chain. Registering from a service provider bypasses panel context and typically breaks navigation grouping, tenancy, and authorization. If you need different behavior per panel, register separate configured instances rather than branching inside one plugin.

Configuration over forking. Pass behavior through the plugin's fluent make()/configuration methods where they exist, and fall back to the published config file for global defaults. Keep your customizations in config/ and your panel provider so future patch releases stay mergeable.

Compose with existing resources rather than replacing them. The common day-to-day integration is attaching the package's actions, columns, widgets, or pages to your resources and pages. Prefer ->headerActions([...]), ->actions([...]), or table/widget registration over subclassing the package's classes — subclassing couples you to internal method signatures that a 3.x minor release may change.

Environment-aware registration. Wrap plugin registration in a config flag or app()->isProduction() check for expensive or noisy features (debug toolbars, demo pages, seeders). This keeps local ergonomics without shipping accidental surface area to production.

Pair with a custom Filament theme if you override views. If you publish and modify the package's Blade views, add their paths to your theme's Tailwind content array and rebuild assets with Vite. Filament 5's asset pipeline will not pick up classes from vendor views automatically.

Test at the Livewire layer. Filament 5 testing leans on Livewire component tests and the livewire()/Filament:: test helpers. Assert on rendered panel pages and on action visibility/authorization rather than on internal package methods — those are the parts most likely to shift between releases.

Upgrade in a branch with a lockfile diff. Because 3.0.0 is version-alignment rather than feature-driven, the interesting part of the diff is composer.lock: check whether the package pulled in a new transitive Filament or support-package constraint, and whether filament/filament moved as a side effect.

Gotchas and Tips

• No 3.x-to-3.x history yet. 3.0.0 is the first Filament 5 release, so there is no patch track record. Pin exactly (3.0.0) for the first deployment cycle and loosen to ^3.0 once a patch lands. Early majors in a new Filament line frequently ship follow-up fixes for panel/asset registration.
• Version constraint mismatches are the #1 install failure. Composer will happily resolve to 2.x if your Filament constraint is loose. Always verify the installed version with composer show after the update, not just that the command succeeded.
• Asset/manifest staleness. If pages 404, icons are missing, or navigation is empty after install, run php artisan filament:upgrade and php artisan optimize:clear before debugging anything else. In production also confirm php artisan filament:assets (or your deploy pipeline's equivalent) runs.
• Config cache in production. Published config changes require php artisan config:cache re-run on deploy. A plugin that reads config at boot will silently use stale values otherwise.
• Panel context at boot. Anything that calls Filament::getCurrentPanel() in a service provider will return null outside a request. Defer such logic to the panel's boot() callback or to middleware.
• Navigation collisions. Two plugins (or a plugin plus your own resources) registering similar navigation groups or slugs produce ordering bugs that look like rendering bugs. Check navigationGroup, navigationSort, and slug explicitly when adding to a panel that already has resources.
• Tenancy. If your panel uses Filament tenancy, verify the plugin's resources/queries are tenant-scoped. First releases in a new Filament major are a common place for scoping to be missed, since tenancy APIs are among the more frequently adjusted parts of the framework.
• Authorization. Confirm policies and canViewAny/canAccess behave as expected on the plugin's pages. Do not assume a plugin ships with authorization wired up — often it just exposes the UI.
• Extension points to prefer: published config, plugin fluent setters, Blade view overrides, and Filament's own action/column registration. Avoid constructor injection into vendor classes or overriding protected methods; those are the least stable surfaces.
• Debugging checklist: php artisan about (confirm Filament version and panel list), php artisan route:list | grep <plugin-slug>, and a dd() of the panel's registered plugins. If the plugin isn't in that list, the problem is registration, not the package.