Ai Translation Bundle Laravel Package

Getting Started

The package is a translation-override layer: AI (or otherwise generated) translations are stored per locale and catalogue as overrides on top of your source strings, and it handles precedence between locales (fr_FR inheriting from fr) plus a coverage report of what is still untranslated.

1. composer require cyllenedigital/ai-translation-bundle — the Flex recipe is unchanged in 1.4.3, so no config edits, no migrations and no mapping changes are needed.
2. Read docs/public-contract.md before touching anything else. It tells you which classes you are allowed to depend on; 1.4.3 renames TranslationOverrideRepository::findByLocaleAndCatalogues() to findValuesByLocaleAndCatalogues(), and that is explicitly outside the contract.
3. First use case: open a catalogue view for a locale you care about, confirm the effective values are what you expect (inherited + own overrides), then check the coverage report to see the gaps. That is the loop you will live in: import → browse → measure coverage → translate the rest.

Upgrading from 1.4.2 is a no-op. The interesting part of this release is that the three reads you hit most often on a real project are roughly 2–3× faster once a locale carries thousands of overrides.

Implementation Patterns

Catalogue browsing. OverrideReader::getTranslationsForCatalogues() now returns scalar rows (key, catalogue, value) instead of hydrating an entity per override. If you are building an admin screen or an API endpoint that lists a whole catalogue, call it and map the rows directly into your view model — do not re-fetch entities per key to "have something to work with". The old entity-per-row shape was the reason these views felt sluggish; keep your side of the pipeline equally lean.

Coverage dashboards. The coverage report sits on getEffectiveOverridesByCatalogue(), which now buckets by precedence instead of sorting. If you build a scheduled job that snapshots coverage per locale, drop it straight into a cached aggregate — it went from ~250 ms to ~80 ms across 7 locales on a 5k-override dataset, which makes it cheap enough to run on request for a single locale.

Deploy / import flow. After an import of AI translations, the translator's override cache is cold. First trans() in a large locale was 344–442 ms and is now 161–276 ms, but it is still the slowest thing on the request. Warm it as a deploy step (or a queued job after import) rather than letting a user pay for it. This is the single highest-leverage pattern with this package.

Locale inheritance. Because precedence is now applied consistently by bucketing, the "effective value" of a key is the same regardless of which read path you go through — catalogue view, coverage report, reference values. Lean on that: you can compute what a user will see using the coverage path and trust it matches runtime translation, instead of re-implementing fallback logic in your own code.

Don't re-sort or re-rank. If you have custom code that sorts overrides by locale specificity before display, delete it. The package ranks each override once, in one place. Duplicating that ordering in your app is now the most likely source of "the admin screen and the site disagree".

Gotchas and Tips

• The renamed repository method is a trap only if you reached past the contract. findByLocaleAndCatalogues() is gone. Grep your codebase for it; if it shows up, you were extending internals and you own that breakage. Everything on the public contract is untouched.
• Query count is unchanged. This release is CPU/allocation work, not N+1 work. If you have a slow catalogue page on a locale with 26 catalogues, you have two separate problems: the per-request overhead (fixed) and your own query pattern (not fixed). Don't assume the upgrade covers both.
• Benchmark with realistic volumes. The gains only materialise with thousands of overrides. On a 200-key project you will see no difference and should not go looking for one.
• Cache misses are still expensive in absolute terms. ~160–270 ms for the first trans() on a 5k-override fr_FR is fine for a deploy job and bad for a cold-cache first page view. Watch your cache invalidation: any config, mapping or import that clears the override cache re-incurs that cost.
• Extension points live behind the contract. If you need custom read behaviour, wrap the repository/reader services behind your own interface rather than subclassing the internals — this release is a good demonstration of why: a pure optimisation renamed a method you would otherwise have overridden.
• Debugging precedence: when a value looks wrong, ask which locale actually supplied it (own override vs inherited) before touching anything. The bucketing change means results are identical to 1.4.2, so a precedence bug you hit after upgrading is almost certainly pre-existing data, not the release.