Filament Translate Action Laravel Package

Technical Evaluation

Architecture fit. The package is a thin Filament form-action wrapper around a machine-translation provider. It slots into the admin layer, not the domain layer: it mutates form state (locale keyed values) and leaves persistence, validation, and business rules to the host application. That is the right boundary for a TPM to endorse — it means adoption does not require changes to models, schemas, or APIs, and removal is a one-line composer remove plus deleting the attached actions. If the product already runs Laravel + Filament with spatie/laravel-translatable (or per-locale columns), the fit is near-native. If the admin is Inertia/Vue, Nova, or a bespoke SPA, this package is inapplicable and the evaluation ends there.

Integration feasibility. Low-to-moderate. Installation is three commands (composer require, publish config, set source/target locales) plus a ->suffixAction(TranslateAction::make('translate')) on each translatable field. The real effort is not installation — it is the surrounding workflow: locale mapping between Filament keys and provider codes, tab-based per-locale layout, validation re-runs after machine output, and deciding where the action is allowed to write. A competent Laravel developer should reach a working demo in half a day; a production-grade rollout across many resources, with guardrails, is a one-to-three sprint piece of enablement work owned by the localization-minded engineer, not a ticket.

Technical risk. Concentrated in four places, none of them the package's own code:

• Provider dependency. The convenience is a translation API, and the API is the product risk: quota, cost, rate limits, unauthenticated fragility, and data leaving the environment. For any content touching customer data, compliance review is the gating item, not code review.
• Silent wrongness. Locale-code mismatches (pt vs pt-BR, zh-CN vs zh-TW) produce plausible-looking output in the wrong language. That is the worst failure mode for a content team because it survives human review, and it argues for explicit mapping plus a review step in the workflow, not a trust-the-button posture.
• State scoping. In repeaters, builders, and relation managers, a mis-resolved state path translates the wrong field silently. This needs a short verification checklist per resource shape before rollout.
• Form-state side effects. Long content inline will stall the Livewire round trip; HTML/RichEditor content can be mangled; translated values frequently exceed source maxLength. Each is a known, cheap mitigation — but only if it is planned, not discovered in UAT.
• Project maturity. 38 stars, a single maintainer, last release October 2024, and a patch release whose only change was missing translations. That is not a red flag for a small internal convenience, but it is disqualifying as a load-bearing dependency in a regulated or long-horizon product without an internal fork plan. Note also that the v1.2.x line targets Filament v3/v4; mixing majors produces confusing Livewire mount errors rather than a clean composer conflict, so pin deliberately.

Key questions for engineering.

• What Filament major are we on, and does the installed constraint match?
• Which translator backs the action today, what does it cost per 1k characters, and who owns the key and its rotation?
• Is there a provider interface we can bind to, so swapping to DeepL or an internal MT service is configuration rather than a rewrite?
• Which fields are in scope — short copy only, or body/rich text — and what is the queueing story for the long ones?
• Does the action write into empty targets only, or overwrite? Who is accountable when it overwrites a human-reviewed string?
• What is our fork-and-maintain willingness if the upstream goes quiet for 18 months?
• Which locales do we actually serve, and is the provider's code set a clean superset of ours?

Integration Approach

Stack fit. Adopt if and only if the admin is Laravel + Filament and the content model is translatable. It is a natural companion to spatie/laravel-translatable: one JSON attribute per field, one action per field writing into the locale keys. For plain per-locale columns (title_en, title_tr), attach per column and point each at its source explicitly — more wiring, same result. Do not attempt to use it as a general translation service; it is an editor affordance.

Migration path. Nothing to migrate. This is additive: no schema change, no data backfill, no API surface change. That is the strongest argument for adoption — it can be trialed behind a feature flag, exercised on a single low-traffic resource, and removed cleanly. The one sequencing dependency is the translator abstraction: if the team binds a provider interface early, every later provider decision is a config change. If they do not, every provider decision becomes a refactor.

Compatibility. Three axes to pin explicitly in composer.json and the deployment notes: the Filament major (v3/v4 era is the target), the Laravel/PHP floor, and the provider SDK or HTTP client version. Treat the Filament constraint as the sharp edge — the failure mode is a Livewire mount error, which reads like an application bug and eats engineering hours. Also flag php artisan config:cache as a deployment step: if the panel's locale list and the action's target list drift because one is cached, the action translates into locales the UI does not show.

Sequencing. Recommended four-stage rollout, each a shippable increment:

1. Prove (week 1). Install, publish config, attach the action to one short text field on one resource. Confirm end-to-end translation, measure latency and cost per action, verify the provider key and quota story.
2. Standardize (weeks 2–3). Build the app-side field helper that wraps TranslateAction::make(...) with team defaults (target locales, provider, confirmation modal) so no resource repeats configuration. Add the locale mapping table. Adopt the per-locale Tabs layout with the source tab first and ->persistTabInQueryString().
3. Guardrail (weeks 3–4). Decide write policy (empty-targets-only on edit forms is the safe default), re-run validation after state update, surface errors on the target tabs, and add the review-before-publish step. Split short fields (inline action) from long copy (queued job, refresh form) rather than letting the button fail on a 6k-character body.
4. Expand (post-launch). Roll to remaining resources once the pattern is proven and the helper exists. Track adoption by counting actions invoked versus target fields left empty — that tells you whether editors actually found it useful or quietly kept pasting from another tool.

Decision framing. This is a build-vs-buy call with a narrow, favorable answer: buy for a lightweight in-admin translate button on an existing Filament stack, build only if the workflow needs approvals, glossaries, translation memory, audit trails, or vendor SLAs — none of which this package attempts. Document that boundary in the decision record so a later request for "approval workflow" is understood as a different product, not a missing feature of this one.

Operational Impact

Maintenance. Low, with one caveat. The package itself is small and stable; the maintenance load lives in the surrounding configuration (locale list, provider key, mapping table) and in the internal helper the team builds. The caveat is upstream velocity: one maintainer, 38 stars, last release October 2024, and a patch-level 2024-10-10 release that only added missing translations. Budget a half-day per year to evaluate currency against the Filament major, and decide up front whether the team will fork. For an admin convenience feature, "pin the version and revisit annually" is a defensible posture — but write it down rather than assuming someone is watching.

Support. No vendor. Support model is internal: one named owner (the engineer who builds the field helper), a short runbook covering the config cache step, the locale mapping table, and where the provider key lives, and a documented decision that translation quality complaints route to the localization/content owner rather than to engineering. Set that expectation early — a translate button creates an implicit promise about output quality, and stakeholders will treat machine output as a feature if nobody frames it as a draft.

Scaling. Two dimensions, with different shapes.

• Team scaling is favorable: the wrapper helper means adding a field or a resource is a one-line change, not a scavenger hunt across 15 translatable fields in 6 resources. Without the helper, adoption stalls.
• Content scaling is where cost and latency bite. Interactive per-field translation is fine at human typing speed and hostile to bulk operations. Batch, cache by content hash, and never fire on afterStateUpdated for every keystroke — a naive autotranslate-on-change will burn quota and degrade the form. Long copy belongs in a queued job. Chunk anything approaching the ~5k-character per-call limit.

Failure modes to instrument and communicate. Ranked by what actually hurts:

• Wrong-language output that looks right. Worst case, because it passes casual review. Mitigation: explicit locale mapping, log the raw provider response alongside detected source language, spot-check pt/pt-BR and zh-CN/zh-TW pairs specifically.
• Quota exhaustion or provider outage. The action fails in the editor's face. Needs a graceful error state, a fallback (typed input still works — the action must never be the only path to filling a field), and an alert on failure rate.
• Mangled rich text. HTML tags translated as words, or tags stripped entirely. Strip before sending for text fields; translate text nodes for rich content.
• Validation failure on save. Translated values exceed source maxLength, form fails on a tab the editor never opened. Mitigation: re-validate after fill and surface errors on the target tab.
• Mis-scoped nested forms. Repeaters, builders, relation managers silently translating the wrong sibling. Verification checklist per resource shape.
• Silent no-op. Stale config cache means the panel and the action disagree about locales; editors click and nothing useful happens. Deployment step, not a bug.

Ramp-up. For editors: minutes. The interaction is a button that fills fields they already understand, and the per-locale tab layout mirrors how translation work already flows — write the source, translate, review each tab. The real training investment is editorial discipline, not tooling: teach translate-then-review, never translate-then-publish, and be explicit that machine output is a draft that will be edited. For engineering: half a day to working demo, one to three sprints to a guardrailed rollout across resources. For the TPM: the useful artifacts are the locale mapping table, the write-policy decision (empty targets only, or overwrite), the in-scope field list split into inline versus queued, and a one-page note on what the package deliberately does not do. That last document prevents the most likely future mistake — someone requesting approval workflows or a glossary and treating their absence as a regression rather than as scope this tool was never meant to cover.