Statamic Ai Translations Laravel Package

Getting Started

This is a Statamic addon (not a standalone Laravel package), so treat it as CMS-adjacent tooling: it hooks into the control panel and the multi-site translation workflow rather than exposing a big public API surface.

1. composer require infofactory/statamic-ai-translations
2. Publish the config: php artisan vendor:publish --tag=statamic-ai-translations-config (check vendor:publish output for the exact tag — Statamic addons vary)
3. Add your AI provider credentials to .env and map them in the config
4. Clear caches: php artisan config:clear && php artisan cache:clear (Statamic caches addon manifests aggressively)
5. In the CP, open a multi-site entry, switch to a secondary site, and use the translation action

Look first at: the published config file (provider, model, source/target site mapping, field whitelist). That file is the contract for everything else — most "it doesn't work" reports trace back to a missing provider key or an unmapped locale.

First use case: translate a single entry from your default site into one secondary site, in the foreground, before you touch queues. Confirm the output quality and field handling on one record before batching anything.

Implementation Patterns

Manual CP translation (the default path). Editors trigger translation per-entry or per-field from the publish form. This is the lowest-risk adoption pattern and needs no infrastructure beyond a working API key.

Background translation (new in 5.1.0). The headline change in this release is an option to push translation work onto the queue instead of blocking the CP request. Enable it in the config and run a worker:

php artisan queue:work --queue=default

This matters most when you have long content, many fields, or slow providers — the synchronous path has a real chance of hitting PHP max_execution_time or a gateway timeout. For anything beyond a single short entry, prefer the background option and make sure your queue is supervised in production (Horizon or a systemd/Supervisor worker).

Programmatic/bulk translation. For migrations or content backfills, drive the translation from a console command or job rather than the CP, iterating entries and dispatching the package's translation job per entry. Chunk by collection and ID range so a failure is retryable instead of all-or-nothing.

Site/locale mapping. Keep source→target site pairs explicit in config rather than relying on inference. If your site handles are en, de, fr, an inferred mapping is fine; if they're default, german, french_ca, be explicit.

Field scoping. Restrict translation to the fields that actually need it (long-form text, Bard/Replicator prose). Do not blanket-translate handles, slugs, asset fields, or structured data you want humans to own — machine-translated slugs are a durable SEO problem.

Integration with editorial workflow. The natural fit is: editor publishes source entry → translation job runs → target entry lands as a draft → translator/editor reviews and publishes. Wire that into Statamic's events (EntrySaved, EntryPublished) with a guard flag so the translation write doesn't re-trigger the listener into a loop.

Gotchas and Tips

• Background translation requires a worker. 5.1.0 adds the option, not the infrastructure. If QUEUE_CONNECTION=sync in production (very common on small hosts), "background" silently degrades to blocking. Verify with php artisan queue:monitor or by inspecting the connection.
• Costs are unbounded by default. There is no per-entry token cap in the addon's control. A Replicator-heavy entry can be expensive. Set provider-side spend limits and start with a field whitelist. Log token usage if the provider returns it.
• Rate limits surface as generic failures. Translation errors often bubble up as a CP toast with little detail. Check storage/logs/laravel.log and enable debug logging for the addon's namespace before assuming the config is wrong.
• Re-running overwrites. Translating again into an existing target entry typically replaces the field content. Any human edits to the translated version are lost — which is another argument for the draft-then-review workflow.
• Locale/site handles are a common misconfiguration. A site not listed in the mapping is silently skipped rather than erroring, so "nothing happened" often means "target site not configured."
• Config caching bites. After editing the config on a cached deployment, php artisan config:cache is required; Statamic's own caches add a second layer. When in doubt, clear both.
• Extension point: if the field-type coverage doesn't match your set (custom fieldtypes, nested Bard sets), the practical fix is a small custom listener or command that extracts the text, calls the translation path yourself, and writes back — rather than fighting the addon's field traversal.
• Version pinning: the 5.0.1 → 5.1.0 jump is additive (no breaking changes signalled), so an in-place upgrade is low risk. Still, run it against a staging copy with a real entry before rolling to production, since queue-related behaviour changes are exactly the kind that don't show up until load.