Filament Translations Gpt Laravel Package

Product Decisions This Supports

• Build vs. buy for translation plumbing, not for translation itself. The GPT call is a commodity. What this package actually ships is the surrounding work: scanning __() / trans() keys, prompt assembly, chunking, queued execution, per-locale write-back into an existing translation store, failure notification, and a permission gate. As of v5 that surface is tested. The realistic alternative is not "we'll integrate OpenAI" — it's "an engineer will hand-roll a script, and it will rot." This package removes a recurring roadmap line item by absorbing the boring parts: chunking, idempotent writes keyed by id, and graceful failure.

• Data egress as a routing decision rather than a legal blocker. OPENAI_BASE_URL, OPENAI_MODEL (default gpt-4o-mini), OPENAI_ORGANIZATION, and chunk_size are env-driven, and any OpenAI-compatible endpoint works. That is the highest-leverage property on this page for planning purposes: it turns "are we allowed to send our copy to OpenAI?" into "which endpoint do we point at?" Route regulated customers to an internal gateway or self-hosted model; cap spend by downgrading the model. That reframing is what moves this from a compliance queue onto a roadmap.

• A defensible pilot scope. The GPT action respects the translation policy's create ability, so the capability is granted by role rather than switched on globally for admins. That enables a real pilot: translators generate and review, localization leads own new keys, everyone else stays read-only. Paired with one completion notification per scan and Octane-safe single registration, this is a workflow you can hand to a small team — not a demo you have to babysit.

• An upgrade epic that a PM should own, not delegate. v5 requires Filament v5, Livewire 4, Laravel 12/13, PHP 8.2+, and filament-translations ^5.0 — a coupled four-part platform move in that order. It will collide with every other admin-panel feature in the same quarter. Scheduling it with a named owner and a release window is a product decision; treating it as a composer update is how sprints die.

• Explicit, budgeted non-goals. No review queues, approval workflows, glossary/terminology enforcement, per-locale QA, token accounting, or vendor billing. Nothing reports spend — you instrument cost yourself (keys × locales × model per scan). Deciding in writing not to build these now is a legitimate output of this evaluation, and it sets the boundary for the next roadmap conversation.

• Where it fits cleanly: internal admin and back-office panels on Filament with drifting keys; pre-launch products localizing into 3–8 locales without a TMS; teams already on Filament who don't want to batch small copy changes out to a vendor. The first use case to validate is deliberately small — one target locale, one non-sensitive group, diff the table before and after, read the output as a translator would. That one run tests auth, chunk sizing, and output quality simultaneously on the cheapest possible dataset.

When to Consider This Package

Consider it when:

• The app is a Filament v5 panel — Laravel 12/13, PHP 8.2+, Livewire 4. That is the only fully supported combination on this release.
• You already run, or have committed to adopting, tomatophp/filament-translations. This is an extension, not a standalone; the parent is a hard prerequisite and its own Filament 5 readiness must be confirmed first.
• Translation drift is a measured bottleneck — many keys, several locales, frequent copy churn, strings silently missing in production.
• Third-party egress is acceptable, or you can route around it through an approved internal OpenAI-compatible endpoint. If neither is true and the copy is regulated, stop here.
• You have a human review step — in-app or procedural — before machine output reaches users. The package will happily write model output into translation records; deciding who reads it first is your job, and the cheapest pattern is translate-into-review-state → diff in the Filament UI → then commit.
• You can staff ongoing re-qualification on each Filament major. This is a 28-star project with zero dependents and a single maintainer-ish footprint — you are an early adopter, and the plan should say so out loud.

Look elsewhere when:

• The frontend is not Filament, or you are staying on Filament v4. The v4 branch is maintenance-only and untagged — no immutable tag, no semver guarantee, a mutable supply-chain target. Acceptable as a short bridge; not a destination.
• You need a real TMS. Assignment, review queues, glossaries, QA, audit history, and billing are out of scope by design, and layering them on means building around the job, not configuring it.
• Strings are sensitive. Keys and values are user-facing copy leaving your perimeter on every scan. If PII or regulated text lives in your lang files, that rule has to be established — and the DPA review done — before the first production scan, not after.
• You cannot guarantee a queue worker. The action dispatches a job; nothing translates inline. Without Horizon/Redis wired up, the feature looks broken rather than failing loudly, and there's no error in the UI to explain it.
• You need cost predictability at scale out of the box. There is no skip-if-already-translated check; re-scans re-pay for unchanged keys. Fine at hundreds of keys, a problem at tens of thousands without a pre-filter or group-scoped scans.

How to Pitch It (Stakeholders)

For executives: this is a small, MIT-licensed plugin that automates the maintenance tax on localization — the missing-key whack-a-mole that quietly consumes engineering time and ships broken copy to non-English users. It plugs into a Filament admin panel we already operate, adds a queued AI-translation action gated by existing permissions, and lets a translator generate and a reviewer approve without a vendor in the loop. Cost is per-scan token spend at gpt-4o-mini rates, and data routing is a configuration choice — we can point it at an internal gateway for any environment that can't send copy to OpenAI. What we are buying is the plumbing around the model call: chunking, retries, idempotent writes, and error handling that we would otherwise build and maintain ourselves. What we are not buying is a translation management system — no glossaries, no approval queues, no QA. Those stay separate decisions.

Risks to state, not bury: it's a 28-star package with zero dependents, so we are an early adopter and should plan to mirror it internally rather than depend on a mutable branch; the v5 requirement forces a coordinated Filament 5 / Livewire 4 / Laravel 12–13 upgrade that the plugin does not cause but does sit downstream of; every scan sends source strings to a third party, so a no-PII-in-translation-keys rule and a DPA review must land before the first production run.

For engineering: the integration surface is a config file and env vars — key, base URL, org, model, chunk_size — plus one job class that owns the API call and the write-back. Read the job before you run it; that's where logging and a preview step go. Non-negotiables: run one locale per scan so partial failures stay bounded; config:cache plus queue:restart after any env change, because workers snapshot config at boot; alert on failed_jobs and don't blanket-retry — a 401 is a revoked key and a 429 wants backoff, not a retry storm. In CI, run the suite with OPENAI_API_KEY unset and assert graceful degradation, and assert the action registers exactly once (the Octane fix makes that a live regression risk). Then, in staging, revoke the key mid-scan on purpose and watch the notification, the failure record, and the alerting — five minutes that tells you more about production readiness than a clean scan of 5,000 keys.