Filament Translatable Laravel Package

Technical Evaluation

Architecture fit. The package slots into the standard Filament plugin contract (Panel::plugin()) and ships a form component (Happenv\FilamentTranslatable\Forms\Component\Translations) plus a fluent translatable() macro that any Filament field can adopt. That is the right shape for a Filament add-on: no service container overrides, no model base-class inheritance, no route or middleware interception. It is additive rather than invasive, which keeps it reversible. Crucially it is a presentation-layer package — it does not own persistence, and it delegates translation storage to spatie/laravel-translatable (default) or astrotomic/laravel-translatable. For a shop already standardized on Spatie, this is a near-zero-architecture-change adoption; for Astrotomic shops it requires swapping in the vendor's AstrotomicTranslatable trait, which is a model-layer commitment.

Integration feasibility. Mechanically simple: composer require, php artisan filament:assets, register the plugin with a locale array, convert a field. The locale list can be a closure (e.g. fn () => Language::pluck(...)), so locale administration can stay in the database rather than hard-coded config. Validation ergonomics (requiredLocale(), requiredDefaultLocale()) and per-locale field decoration (decorateTranslationField()) cover the two requests content teams most often raise. Estimated effort for a first resource is under a day for a Filament-fluent developer.

Technical risk.

• Adoption signal is weak. 11 stars, 0 dependents. There is no public corpus of production edge cases, and no third-party evidence of behaviour inside repeaters, relation managers, wizard steps, or nested Translations components. CI badges for tests, PHPStan and Rector are a genuine quality positive but validate the author's own scenarios, not ours.
• Bus factor of one. happenv-com is a single vendor. A Filament major release could leave us pinned and unpatched. Mitigation is a fork-and-own decision made before adoption, not after.
• Backend lock-in. The Astrotomic path requires a vendor-supplied trait and an enum mode set at plugin, component, or field level. That is flexible, but it means translation mode can be set in three places — configuration drift is a real failure mode.
• Documentation is README-only. No versioned docs site, no upgrade guide beyond the version matrix table, no API reference for the Translations component's full method surface.
• Footgun in the fluent API. The macro switches context from field to component, and the README explicitly warns that required() must precede translatable(). Order-sensitive fluent chains are a code-review and onboarding tax.
• Scope gap. The README documents forms only. Table columns, infolists and API serialization of translated values remain our problem.

Key questions.

1. Does the component behave correctly inside repeaters, builders, relation managers and multi-step wizards, where nested state paths are already non-trivial?
2. How are Astrotomic translation relations hydrated and dehydrated on edit forms — does the component handle the relation load, or must we pre-load?
3. What is the supported PHP / Laravel / Filament matrix per package major, and what is the vendor's stated policy for shipping support for a new Filament major?
4. Is there a path to translate the package's own UI strings?
5. What is the intended display-side story (table columns, infolists), or is that explicitly out of scope?
6. Are there performance characteristics we should know about with 8+ locales on a wide content form?

Integration Approach

Stack fit. Laravel + Filament 4.x or 5.x with spatie/laravel-translatable already in place is the low-friction path — package v4 covers both Filament 4 and 5; Filament 3 requires the older v2 line under a different namespace, so a mixed-version estate needs two installs or an upgrade first. Astrotomic shops are supported but pay the trait-swap cost. PHP 8.2+ should be assumed and verified against the Composer constraint before committing.

Migration path. If we already store translations as Spatie JSON columns, there is no data migration — the package reads and writes the same shape. That is the single strongest argument for the Spatie route and should drive the backend decision. If we are on Astrotomic, or on hand-rolled per-locale columns, treat this as a data-shape project with its own migration plan, not a UI swap. Backend choice should be locked at the start; switching later means a full translation-table/JSON re-projection across every translatable model.

Compatibility. Two things must be version-pinned and checked in CI: the package major against the Filament major, and the translation backend against the model traits. The published asset step means the deploy pipeline needs php artisan filament:assets added alongside existing asset compilation — a small but easily-forgotten requirement that fails silently in production as broken tabs.

Sequencing.

1. Spike branch: install, publish assets, register the plugin, set locales from a closure over the existing locale source of truth. Prove the deploy step in staging.
2. Convert one low-risk resource with two or three fields — ideally one already using Spatie. Validate create, edit, validation failure, and locale switching.
3. Stress the edges the README does not cover: repeater nesting, a second Translations component on the same form, Astrotomic mode if applicable.
4. Establish a house convention — plugin-level locale config only, required*() before translatable(), one named Translations component per form — and capture it in an internal runbook before broad rollout.
5. Roll out resource by resource; then resolve the display side (table columns, search, API output) separately, since the package does not address it.
6. Decide and document the fork/own/abandon trigger for the next Filament major.

Operational Impact

Maintenance. Small dependency surface (one Composer package, one Filament plugin registration), but a live tracking obligation: every Filament major is a potential forced upgrade, and the vendor's release cadence — recent releases and CI on PHPStan/Rector — is encouraging but unproven across a major. Pin the version, watch releases, and budget roughly a day per Filament major for validation. Own a fork or a documented replacement plan; do not let a single-vendor dependency sit unexamined in the critical path of the CMS.

Support. No commercial support, no dependents, no Stack Overflow footprint. Internal ownership is mandatory: one named engineer accountable for the plugin, with the locale configuration treated as team-owned config. Escalation path is upstream issues then a local fork.

Scaling. The package is form-render only; scaling concerns are inherited from the backend. Spatie JSON columns make cross-locale search and indexing awkward at volume — plan for generated columns or a search index if content search spans locales. Forms with many locales multiply field count and per-locale required-rule evaluation; acceptable for editorial forms, worth load-testing on the widest content type. No caching or queue implications.

Failure modes.

• Assets not published in a deploy → locale tabs render broken or unstyled; caught only by visual QA.
• Trait mismatch (Astrotomic model without the vendor trait, or wrong translation mode) → fields hydrate empty or writes drop silently; the highest-severity failure because it looks like "no one entered translations."
• Locale drift between plugin config, database locale table and app.fallback_locale → missing tabs or orphaned content.
• Name collisions when two Translations components share a name → actions and state bleed between them.
• Fluent-chain ordering (required() after translatable()) → validation silently not applied.
• Filament major bump without a matching package major → form API breakage on every translatable resource at once.

Ramp-up. Low for anyone already fluent in Filament — the macro is discoverable and the README examples are copy-pasteable, so a first conversion is a half-day. The real ramp-up cost is in the unwritten parts: nesting behaviour, display-side handling, and the ordering rules. Budget one engineer-day for a first resource plus half a day to write the internal runbook, then treat subsequent resources as near-zero.