Translation Log Bundle Laravel Package

Technical Evaluation

Architecture fit — the capability fits the roadmap; the artifact does not fit the stack. The problem this package names is real and currently unmeasured in our product: users in non-primary locales see raw keys (checkout.title) or silent English fallbacks, and we have no runtime signal telling us how often. As a TPM, that is the thing worth taking from this evaluation — a defect class with user-visible impact, no telemetry, and a cheap instrument. The shipped code is a Symfony bundle built on the Symfony service-container/compiler-pass model and translation-component events; our stack is Laravel, where none of those extension points exist. So the deliverable from evaluating this package is a decision and a scoped requirement, not a dependency.

Integration feasibility — treat as zero. This is a reference implementation, not an install candidate. Composer resolution against PHP 8.1+ and Laravel 10/11 will almost certainly fail on constraints, and even on success nothing would register in our framework — no service provider, no discoverable listener. Any plan that includes "integrate the package" should be closed now rather than after an engineer burns a sprint proving it. The realistic path is a reimplementation of ~80 lines behind Laravel's translator contract.

Technical risk — low if we do not adopt, high if we do. The zero-star/zero-dependent profile means no downstream validation, no issue history, no security response path, and no maintainer to escalate to. That is a supply-chain liability attached to a logging nicety. The blast radius of not using it is zero, which is why "steal the pattern" is the correct risk posture. The residual risk shifts to the thing we build: it sits on the hot path of every translation call, so its failure modes (throws, PII in logs, log floods) become our risk and need explicit requirements.

Key questions for the requester and for the roadmap:

• What triggered this — a specific incident, a specific market launch, or general i18n hygiene? The answer sets priority and scope.
• Do we already have build-time i18n coverage (CI key-diff, static extraction)? If not, that is cheaper and catches more than runtime logging; runtime logging is the complement, not the starting point.
• Who is the named owner who will triage misses weekly? A capability with no owner is a capability we should not fund.
• What log destination and retention — dedicated Monolog channel, structured JSON to the aggregator, or nothing yet? Determines whether volume is trivial or needs sampling from day one.
• What attribution do we need per miss — locale, environment, release, route — and do we need to feed an existing localization vendor (Phrase, Lokalise, Crowdin) or an internal lang/ sync pipeline?
• Does any stakeholder believe we are buying this? Correct that expectation before it reaches a budget line.

Integration Approach

Stack fit — capability yes, package no. Laravel exposes two seams: a decorator bound over Illuminate\Contracts\Translation\Translator in a service provider (version-safe, my recommendation), or a missing-translation event listener in versions that dispatch one (verify per minor, the surface has moved). Scope the artifact as a small internal package we own — internal/translation-audit — with a published version, not dev-main, and a one-page README that names the owner and the triage workflow.

Migration path — there isn't one, and stating that explicitly is part of the deliverable. There is no upgrade route from a Symfony 2-era bundle to a Laravel package. If the original source has a reusable idea — key de-duplication, for instance — read it under license, cite it, and move on. The framing to stakeholders should be "reimplement the pattern," never "fork the dependency." That keeps the license, security, and maintenance conversations short.

Compatibility targets to pin before the build starts: PHP 8.1–8.3, Laravel 10 and 11, PHPUnit against both framework minors, and dependencies limited to illuminate/translation and illuminate/support. Pin these in the ticket so "it works on my machine" does not reopen scope.

Sequencing, with decision gates a TPM can hold people to:

1. Spike, half a day. Confirm the Symfony/Laravel mismatch in a scratch container and close the "can we just install it?" thread permanently. Output: one-page decision note, no debate afterward.
2. Coverage audit, half a day. Inventory what i18n tooling already exists. If a CI key-diff exists, this narrows to runtime-only dynamic keys; if nothing exists, the build-time check goes first and this moves down the backlog.
3. Build, two to three days. Decorator, provider binding, config (enabled, channel, sample rate, ignore-prefix allowlist), fail-open handling, tests.
4. Pilot, one week. One service, one non-primary locale, staged environment. Success criterion agreed up front: does the captured miss list overlap with the manual QA list, and does it surface misses QA did not know about?
5. Rollout gate. Promote to production only with sampling, a log budget, and the named owner in place; otherwise shelve as a staged-only diagnostic.

Explicit non-goal for the roadmap line: do not attach this to user-facing traffic without a rate limit and an ignore allowlist. It runs on every translation call.

Operational Impact

Maintenance — low, and that is the argument for building. We trade an untracked, unmaintained upstream for an internal package we can reason about. Cost is a few hours per Laravel major to re-verify the translator contract. Keep it deliberately narrow so it never grows a roadmap of its own; the moment it needs one, it has become the thing we were avoiding.

Support — vendor support is zero either way, so make it ours deliberately. No maintainer, no CVE feed, no cadence on the original. Our internal on-call covers the built version. Worth saying to stakeholders plainly: the support risk we retire by not adopting exceeds the support risk we take on by writing 80 lines.

Scaling — the dominant cost is log cardinality, not compute. One comparison and a conditional write per call is negligible. The real risk is dynamic keys (interpolated strings, IDs, user content used as keys) generating unbounded unique misses and swamping the aggregator. Requirements from day one: sample rate, per-key dedupe over a short cache window, max key length, ignore-prefix list, and an explicit per-service log budget with an alert when exceeded. Without the budget, the diagnostic becomes the incident.

Failure modes to write into the ticket as acceptance criteria:

• Translation-path breakage. If the decorator throws, page render fails. Must fail open — catch everything, delegating to the underlying translator, swallowing logging errors. Non-negotiable.
• Log backend outage or backpressure. Dedicated channel with an async/queued handler; drop misses, never requests.
• PII leakage. Keys and parameters can contain names, emails, addresses. Log keys and parameter names, or hash values. This is the one failure mode with regulatory consequence and should be a hard gate, not a nice-to-have.
• Noise-driven abandonment. The most likely real-world failure is that it works, floods the logs, nobody triages, and it gets disabled in a month. Pair rollout with a named owner and a recurring triage slot, or do not ship.

Ramp-up — under a day for a mid-level engineer on the code; the real onboarding cost is process. The service-provider and decorator patterns are familiar and the surface is small. What needs writing down and handing over is the triage workflow, the config knobs, and the sampling policy — plus a short demo to the team that will actually read the misses. Ship the docs and the owner in the same PR, not a follow-up ticket.

Bottom line for the decision log: do not adopt th/translation-log-bundle. It is a zero-signal, unmaintained Symfony artifact with no install path into Laravel. The capability is worth having and worth a roadmap line, scoped as a small internal Laravel package with sampling, dedupe, PII-safe logging, and fail-open semantics — gated on a named triage owner. Use this package as evidence the problem is recognized, and as a requirements checklist, not as a dependency.