Ai Translation Bundle Laravel Package

Technical Evaluation

Verdict: low-risk patch; upgrade is recommended once the one removal is confirmed unused in our code.

Architecture fit. v1.4.3 is a read-path optimisation entirely inside the bundle's override storage and precedence layer. It replaces per-row entity hydration with scalar row selection in OverrideReader::getTranslationsForCatalogues(), and replaces sort-based precedence resolution with bucketing in getEffectiveOverridesByCatalogue() and in the reference/inherited-value paths. It introduces no new extension points, no configuration surface, and no contract change — the integration shape is identical before and after. One caveat worth stating plainly: this is a Symfony bundle (CylleneDigital/AiTranslationBundle), not a Laravel package. If the target stack is Laravel, none of this is drop-in — the override repository, translator decoration, and cache warmers are wired through the Symfony DI container, so fit is conditional on a service-container bridge that costs far more than this patch is worth.

Integration feasibility. Composer bump within the 1.4 line. No recipe change means no Flex re-run, no config diff, no mapping or migration. The only source-level hazard is the rename of TranslationOverrideRepository::findByLocaleAndCatalogues() to findValuesByLocaleAndCatalogues(). The maintainer correctly notes the repository is outside the documented public contract — but a method removal in a patch release still fails at runtime rather than at composer install, so any application code, test double, fixture, or compiler pass touching it breaks silently on deploy.

Technical risk. Low. Results are unchanged and the query count is unchanged; the change is CPU work removed from the read path, not a change in semantics. The larger risk is over-claiming value: the published gains (≈2.7× on grouped reads, 219–232 ms → 80–85 ms) were measured at 5,018 overrides per locale across 26 catalogues and 7 locales. A tenant with a few hundred overrides will see noise-level improvement and should not be sold on the headline number.

Key questions.

1. Do we extend, decorate, or mock TranslationOverrideRepository anywhere, including tests and static analysis baselines?
2. What is our real override volume per locale today, and projected at 12 months? Below ~1,000, this patch is operational hygiene rather than a performance win.
3. Which of these paths do we actually exercise — catalogue view, coverage report, translator warm-up, or only runtime trans()? Gains land in back-office surfaces; end-user latency may not move.
4. Do we have a harness to re-measure on our own data rather than trusting the vendor table?
5. Symfony or Laravel — is there an adapter plan, or is the framework mismatch already disqualifying?

Integration Approach

Stack fit. Conditional on framework. Direct fit on Symfony; on Laravel this package needs a bridge regardless, and the release neither advances nor blocks that decision.

Migration path. None required. Bump the constraint, composer update, deploy. No data changes, no cache schema changes, so existing override caches stay valid and no warm-up is mandated.

Compatibility. Patch release; PHP and framework floors should be unchanged, but verify against our pinned versions before bumping. The renamed repository method is the only compile/runtime surface — grep the old name across application code, tests, fixtures, and any custom repository decoration or service override.

Sequencing.

1. Static check for findByLocaleAndCatalogues() across all first-party code.
2. Bump in a non-production environment.
3. Run the existing translation suite plus a spot-check that rendered output for a high-override locale is identical to 1.4.2.
4. Capture before/after timings on a representative locale to validate the claim locally.
5. Normal rollout — no coordinated release with other services, no cache flush, no backfill.

Operational Impact

Maintenance. Near-zero incremental. No new config to drift, no scheduled job, no schema. Routine dependency hygiene. The rename is the one thing that can rot in a fork and only surface under load in an admin screen.

Support. The public-contract document is the escalation boundary; the vendor has explicitly scoped the change to non-contract internals, and there is no deprecation to track. Patch-level release from the vendor.

Scaling. Improves request-path CPU and read latency; does not reduce query count, so database load, connection-pool sizing, and index strategy are untouched. Cold-cache first trans() is still 161–276 ms at 5k overrides — if we run many cold locales (deploys, evictions, per-tenant warm-up), plan capacity against that figure, not the warm path. The material gains are concentrated in back-office reads (catalogue view, coverage report), so this is a tooling-responsiveness improvement more than a customer-facing one.

Failure modes. No new failure mode is introduced. Pre-existing ones persist: cold cache after deploy or eviction, memory pressure when materialising large override sets, and — newly relevant — any code still calling the removed method failing at runtime rather than at install. Post-deploy cache warm-up remains the standard mitigation.

Ramp-up. Trivial for a team already on 1.4.x; the change is invisible to developers apart from the repository signature. Adopting the package fresh is a different budget entirely — the cost sits in Symfony wiring and AI provider configuration, not in this patch.