Filament Translations Gpt Laravel Package

Getting Started

Confirm the stack before writing code. This is an extension, not a standalone package: it adds an action to the tomatophp/filament-translations Filament resource. You need Laravel 12/13, PHP 8.2+, Filament v5, Livewire 4, and tomatophp/filament-translations ^5.0 already installed and rendering in your panel. If you are on Filament v4, you are on the v4 branch — a separate decision, not a fallback.

composer require tomatophp/filament-translations-gpt
php artisan filament-translations-gpt:install

The v5 installer runs in-process, so it is safe inside a provisioning script or container entrypoint.

Configure via env, not code edits:

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_ORGANIZATION=
OPENAI_MODEL=gpt-4o-mini

chunk_size lives in the published config. Then:

php artisan config:cache
php artisan queue:restart   # workers snapshot env at boot

Where to look first, in order:

1. The generated config file — that is the entire public surface: key, base URL, org, model, chunk size.
2. The translations resource in your panel — confirm the GPT action appears where expected and only for authorized users.
3. The job class the action dispatches. Read it before running it: it is the only place that talks to the API and writes back, and it is where you will add logging or a preview step.

First use case: one target locale, one small non-sensitive translation group. Run the action, watch the queue worker, diff the translations table before and after, and read the output as a translator would. You validate auth against your endpoint, chunk sizing, and output quality on the cheapest possible dataset. Do not start with your whole lang/ directory.

Implementation Patterns

Treat the action as a queue workflow, not a button. The action dispatches a job; nothing translates inline. A real worker (Horizon/Redis) must be running before you demo it — otherwise the scan silently does nothing and looks broken.

Gate on the policy, and verify dispatch is gated too. The v5 action respects the translation policy's create ability. Confirm that gate covers job dispatch, not just button visibility; otherwise a crafted request can still trigger paid API calls. Use it as your pilot lever: grant create to a small translator group, read-only for everyone else.

Route by environment, not by branch. Keep gpt-4o-mini for dev and bulk fill. Point staging (and anything regulated) at an internal gateway via OPENAI_BASE_URL — any OpenAI-compatible endpoint works — and validate auth/org headers there before production ever runs a scan. Validate the model name against that endpoint; compatibility does not mean an identical model catalog.

Scan per locale, not per key. The unit of work is a scan: one completion notification, one failure surface. One locale at a time means a partial failure is a bounded gap, not a half-translated matrix.

Insert a human review step you own. The package writes model output into records and implements no approval, glossary, or QA. Cheapest pattern that works: translate into a review state, diff in the Filament UI, then commit. If the parent package writes back to lang/, that diff belongs in a PR — an AI-generated lang/de.json in code review is the review gate.

Tune chunk_size against two failure modes. Large chunks risk truncation and timeouts; small chunks multiply requests and rate limits. Start near your average key length × 50 and watch for 429s versus truncated completions. Markdown-fenced answers are accepted, but do not assume every model fences consistently.

Skip unchanged keys yourself. There is no built-in "already translated" check, so re-scans re-pay for untouched keys. Pre-filter or scope scans to changed groups before this becomes a habit.

Instrument cost. Nothing reports tokens or spend. Log keys × locales × model per scan so "what did this month cost" has an answer.

CI worth having:

• Run with OPENAI_API_KEY unset and assert graceful degradation, not an exception.
• Assert the action registers exactly once — the Octane fix makes double registration a real regression risk.
• Run the package's own suite as a baseline before layering your changes.

Gotchas and Tips

No key means a silent no-op. Nothing is sent when OPENAI_API_KEY is unset — safe for staging, dangerous in production. "The button does nothing" is almost always a missing key, a stale config:cache, or a worker that booted before the env changed. Check all three before reading job code.

php artisan queue:restart after every env change. Long-running workers hold booted config. This one line saves hours.

Failures land in failed_jobs. v5 notifies the user and fails cleanly rather than crashing — better, but invisible unless you look. Wire failed-job alerting and do not blanket-retry: 401 means a revoked key; 429 wants backoff, not a retry storm.

Partial chunk failure leaves a locale inconsistent. Writes are keyed by id, so re-running the scan is idempotent for already-written values. Recovery is "fix the cause, re-run the scan," not "restore the table." Also confirm a re-scan cannot clobber a human-edited value.

Same key in two groups was a data-loss bug before v5. If upgrading, check whether duplicate keys across groups were overwritten and whether they are recoverable.

Translation keys are user-facing copy leaving your perimeter. Every scan ships source strings to a third party. Make it a hard rule that keys and values never carry PII or regulated text, and finish the DPA review before the first production scan.

OPENAI_BASE_URL needs the versioned path. Most compatible gateways expect the trailing /v1; a self-hosted model may not recognize gpt-4o-mini at all.

The v4 branch is maintenance-only and untagged. No immutable tag, no semver guarantee. If you must stay on Filament v4, mirror it internally and track upstream commits rather than pointing Composer at a mutable ref.

The upgrade is four parts, in order: Filament v5 → Livewire 4 → filament-translations ^5.0 → this package. The breaking surface is the framework majors; the plugin's API is stable and implies no data migration. Check that your other admin plugins have Filament 5 support — this one won't be your constraint, a neighbor will.

Extension point is configuration, not forking. The plugin is thin: swap model, base URL, or chunk size via env/config. Terminology enforcement, QA, and approval queues are out of scope — add them as post-processing around the job rather than patching the action.

Deliberately test failure. Revoke the key mid-scan once in staging. Watch the notification, the failed_jobs entry, and your alerting. Five minutes there tells you more about production readiness than a clean 5,000-key scan.