Filament Localizable Resources Laravel Package

Technical Evaluation

Architecture fit. This is a thin presentation-layer package: it does not introduce a service, a datastore, or a runtime dependency, and it assumes (rather than owns) the translation storage layer — typically spatie/laravel-translatable with a JSON translations column. From a product-architecture standpoint that is the right shape. The localization capability an admin needs (per-locale tabs, fallback behavior, locale-aware columns) is added on top of resources you already run, so the blast radius of adoption is limited to the resource classes you opt in. It is a build-vs-buy decision that resolves cleanly toward "buy the UI layer, own the data layer."

Integration feasibility. Low effort to prove out: install, pin Filament and the package together, register locales in one config location, convert a single small resource with two translatable fields. That spike answers the only question that really matters pre-commitment — whether the package's default UX is tabs-per-locale or per-field locale inputs, since those produce very different editorial workflows and the wrong one is expensive to unwind. A half-day spike and a one-to-two-day integration for the first resource is a realistic planning number.

Technical risk. Ranked:

• Filament major-version coupling (high). Localizable resource packages are bound to Filament's form/table schema API, and v3 vs v4 differ substantially. Filament also ships frequent minors, which is the realistic breaking-change vector. This is the dominant lifecycle risk and the one to price into any roadmap commitment.
• JSON column semantics (high, but not the package's fault). ->searchable() and sortable translatable columns hit the raw JSON column and return cross-locale nonsense; unique rules don't work per locale. The package does not solve this, so it is real engineering scope that must be scoped alongside adoption or the localization story will be judged broken at launch.
• Fallback-on-read vs fallback-on-write (medium). The fallback is applied on read, not on write, which generates "saved fine, displays empty" reports. This is a requirements decision, not a bug, and it needs to be made and documented before editors are trained.
• Stewardship (medium). Three stars, a single thin patch release with only a compare link as a changelog, and no visible release narrative. At v1.0.x this is a small-maintainer dependency on a non-critical path. MIT plus a small source surface makes vendoring or forking a credible mitigation.
• Locale switcher state (low-medium). If editing locale is stored in session, it can leak across panels and tenants. Key it by panel ID (and tenant ID in multi-tenant installs).

Key questions to close before committing.

1. What Filament version does the package's composer.json actually constrain, and is a v4 path planned? Pin from the manifest, not from the README.
2. Does the package ship a locale switcher, or does it expect the host app to provide panel/session state?
3. Trait or base resource class? A trait composes with an existing base resource carrying tenancy, policies, and navigation; a base class creates a "two base classes" dead end.
4. How are required-per-locale rules expressed — closure-driven per locale, or duplicated per tab?
5. Does it intercept searchable/sortable translatable columns at all, or is that left entirely to the app?
6. Issue responsiveness and recent maintainer activity — enough to put this on a critical path, or only on an elective one?
7. Who owns the model-side storage backend decision (spatie vs. custom accessors) so API and console paths behave identically to the admin?

Integration Approach

Stack fit. Laravel + Filament panel, translation storage already in place. No new infrastructure, no external service, no data migration. It aligns with Laravel translation conventions rather than inventing a parallel model, which keeps the exit cost low — removing the package leaves your resources and data intact.

Migration path. There is no schema migration. The change is additive at the code layer and disruptive only at the workflow layer: editors move from single-locale forms to per-locale tabs, and existing resource form schemas need re-shaping. Treat this as a UX change-management item, not a technical migration. v1.0.2 is a patch bump with no advertised breaking changes, so there is no coordinated upgrade to schedule.

Compatibility. Verify the PHP/Laravel/Filament matrix explicitly and pin ~1.0.2 in production. Put the package plus Filament in a CI matrix so a Filament minor bump surfaces as a red build rather than a production regression. Because release notes are thin, CI is the real compatibility contract.

Sequencing.

1. Spike on one low-risk resource (e.g., a Page with translatable title/body), editor-visible, behind a flag if possible.
2. Consolidate the locale list into one config source of truth referenced by forms, tables, and the switcher — never hardcode locale arrays inside resources.
3. Build the panel-scoped (and tenant-scoped) locale switcher before rolling out to a second resource.
4. Roll out resource by resource; apply a trait per resource rather than inheriting a base class.
5. Address search, sort, and per-locale uniqueness at the database layer (generated columns, json_extract, or Scout) as a separate tracked workstream.
6. Publish the fallback convention (null vs. copy-fallback for empty non-fallback locales) and the "fallback required, others optional" validation rule.

Decision gates. Go/no-go after the spike on two criteria: does tab-per-locale match how your editors actually work, and does the integration survive a Filament minor bump in CI? If either fails, the fallback is to keep translations in the model layer and defer the admin UX.

Operational Impact

Maintenance. The package itself is small and cheap to maintain. The surrounding plumbing is not: search indexing, sort behavior, unique validation, and locale session state all become yours to own. Budget for the plumbing, not the dependency. Pin exact-ish versions in production and let CI catch Filament bumps.

Support. Expect a recurring "I saved it but it shows empty" ticket stream driven by read-time fallback semantics. Pre-empt it with a one-page internal convention doc and translated attribute names in lang/*/validation.php, otherwise editors see mixed-language validation errors. Editorial onboarding is a short guide, not a training program.

Scaling. Fine at typical admin content volumes. Two ceilings: query behavior (calling getTranslation() in table column closures across a page of rows invites N+1 unless relations are eager-loaded) and locale count — tab-per-locale is workable at two to four locales and becomes unusable past roughly six, at which point the UX, not the package, is the constraint. If the roadmap points at many locales, revisit the interaction model before scaling the locale list.

Failure modes. Filament upgrade breaks the schema API; search and sort return cross-locale garbage at launch; locale state leaks across panels or tenants; missing translations present as silent blanks rather than errors; package goes dormant. The last one is mitigated by MIT licensing and a small source surface — vendoring or forking is a realistic contingency rather than a rewrite.

Ramp-up. Low for engineers already fluent in Filament: half a day to spike, one to two days to integrate the first resource, then incremental per-resource work. Ongoing operational load is negligible once the fallback convention and search/sort handling are settled.

What to instrument. Number of locale-gap tickets opened by ops, time from spotting a locale gap to shipping the fix, and any post-launch sort-or-search defects on translatable columns. Those three metrics tell you whether the package delivered the intended outcome — moving translation work out of the engineering backlog and into the admin — or merely relocated it.