Ai Translation Bundle Laravel Package

Product Decisions This Supports

• Unblocking the translation admin UI at realistic volume. A catalogue view of a locale with ~5,000 overrides drops from ~220 ms to ~85 ms, and the coverage report across 7 locales from ~250 ms to ~80 ms. Anything that was previously deferred as "too slow to ship" — a translator-facing catalogue browser, a coverage/gap dashboard, per-string reference values — is now shippable without pagination hacks, denormalised caches, or a queue-backed read path.
• Regional-variant expansion as a roadmap item. The measured win is on fr_FR inheriting from fr, i.e. the exact shape of de_DE/de, pt_BR/pt, es_MX/es. If regional variants were previously costed as "same work again per market," this release makes each additional variant a low-marginal-cost rollout decision rather than an engineering project.
• First-paint budget for translation surfaces. The cold-cache trans() path (worst case ~440 ms) falling to ~160–275 ms changes whether a translation-heavy page can render synchronously on first request or needs a warmup job. That is a build-vs-buy input: it removes a common argument for offloading reads to an external TMS/CDN.
• Build vs buy, narrowed but not settled. If the internal option was "build our own override store with precedence and inheritance," this package now covers the read performance that usually kills that build. The remaining buy-side arguments are workflow (review/approval, vendor management, MT quality scoring), not speed — so scope the buy decision to workflow, not to performance.
• Audit and QA features are now cheap. Coverage reporting and effective-override inspection are the primitives behind "what will this locale actually render, and where did it come from?" Features like machine-translation review queues, staleness flags, and pre-release locale diffing can reuse these reads instead of needing a new data model.
• No infra cost lever attached. Query count is explicitly unchanged, so this is a CPU/entity-construction win, not a database-load win. Do not plan a database sizing or read-replica decision around this release.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP and the product needs a translation override layer on top of static language files — content that non-developers edit after deploy.
• Locales have fallback chains (regional variant inherits from base language) and the product must explain which value wins. Precedence correctness is a core behaviour here, not something you would bolt on.
• Override volume per locale is in the thousands, not dozens. This release is specifically the answer to "our catalogue screens got slow once the translators started working." Below a few hundred overrides, the optimisation is irrelevant and other criteria should dominate.
• Localisation is product-owned rather than engineering-owned: translators, regional marketers, or an agency need to work without a deploy.
• You want the override store to be internal and swappable. The renamed repository method is explicitly outside the public contract, which is healthy — but it also tells you not to build product logic against internals.

Look elsewhere when:

• You need a full TMS: approval workflows, vendor/agency management, per-word billing, MT quality scoring, in-context screenshot translation. This is a bundle, not a localisation platform.
• Translation coverage and quality are a compliance or contractual obligation with named SLAs. Prefer a vendor with support terms over a single-maintainer package.
• The product is not Laravel/PHP, or the team standardises on a framework-agnostic layer.
• The real problem is authoring content in multiple languages at all — if nobody is writing or machine-generating the translations, an override store is scaffolding around an empty process.
• You require semantic-versioned stability on the override data access layer. The public contract covers behaviour, not the repository API; treat any direct repository use as a fork risk.

Adoption checklist before committing:

• Grep application and package code for findByLocaleAndCatalogues() — removed here, not public, but any third-party or in-house extension referencing it will fatal.
• Confirm you are not depending on entity objects from getTranslationsForCatalogues(); it now returns scalar rows. Results are stated unchanged, but the return shape at the repository level is a caller-visible detail.
• Benchmark against your own worst locale rather than the published 5,018-override figure. Treat the published numbers as a shape (≈2.5–3x on grouped reads) not a promise.

How to Pitch It (Stakeholders)

To executives — one paragraph: Localisation has been a hidden engineering cost: every translated string that marketing or a regional team wants changed becomes a ticket, and the tooling we would need to remove that dependency has historically been too slow to put in front of non-technical users. This release fixes the speed problem at the volumes we actually operate at — translation catalogue screens, coverage reporting, and first-render translation loads are now roughly 2.5–3x faster on our heaviest locales — with no migration, no configuration, and no change to stored data. It is a routine version bump that converts "can we let regional teams own their copy?" from an engineering project into a product decision.

To engineering — what to know:

• Upgrade is a lockfile bump. No config, mapping, migration, or contract change; the Flex recipe is unchanged. Results are stated to be identical and query counts are unchanged, so no database or cache topology work follows from this.
• One internal method was removed: TranslationOverrideRepository::findByLocaleAndCatalogues() → findValuesByLocaleAndCatalogues(). It is outside the public contract, but verify no application code, custom command, or internal extension calls it.
• The mechanism is worth understanding, because it is the pattern to reuse: grouped catalogue reads now select scalar rows instead of hydrating an entity per override, and precedence is applied by bucketing instead of repeated sorting — with ranking hoisted to once-per-override on a cache miss. If we maintain any read path with the same "hydrate then sort" shape, this is the same fix.
• Residual risk is maintenance, not correctness. Plan for the possibility of upstream drift in a package that sits on the translation read path, and keep the public contract doc as the boundary we code against.

To the localisation/content stakeholders — what changes for you: Catalogue views and coverage reports on your largest locales should feel roughly three times more responsive, and the first load of a page in a regional variant is materially faster. Nothing you do changes, and nothing needs re-translating.