I18N Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin presentation-layer adapter: it reads Laravel's translation repository and serializes strings into the rendered HTML via a Blade directive, then exposes a small JS helper (__()) that mirrors Laravel's PHP helper.
• High fit for server-rendered Blade apps with light client-side behavior (Alpine, vanilla JS, jQuery, Livewire, Turbo). It preserves the existing single-source-of-truth for translations in lang/ and avoids a parallel JS translation pipeline.
• Poor fit for an API-first or SPA architecture where Blade layouts aren't the delivery vehicle; there the same goal is better served by a JSON endpoint or build-time extraction (e.g., laravel-vite-plugin + i18n loader).
• It does not change routing, persistence, auth, or queueing — the architectural blast radius is confined to view rendering and front-end bootstrapping.

Integration feasibility

• Standard Composer install with package auto-discovery, optional config publish, and one directive added to the base layout. Realistic effort: half a day for a proof of concept, 2–5 days to roll out with conventions and tests.
• No database migrations, no schema changes, no new infrastructure. This is important for the TPM case: the cost is developer time and payload, not platform spend.

Technical risk

• Payload growth (primary risk). Every key shipped on every page grows linearly with key count × locales. A 3,000-key, 5-locale app can add tens to hundreds of KB to each HTML response before compression. This directly affects TTFB, cache efficiency, and mobile performance.
• Caching and locale correctness. Because translations are inlined into HTML, any CDN or full-page cache keyed without locale or translation version will serve stale or wrong-language content. This is an operational incident waiting to happen and needs an explicit cache-key decision.
• Escaping/XSS surface. Translation strings are interpolated into a script context. If any translation value is user-influenced (tenant-defined labels, CMS content), correct JSON encoding and context-aware escaping must be verified, not assumed.
• Global namespace collision. Defining window.__ can conflict with existing helpers, analytics shims, or other i18n packages. Confirm before rollout.
• Vendor concentration. 128 stars and MIT licensing are fine, but this is effectively a small-maintainer package. No SLA, limited test surface visibility, and unknown backward-compatibility guarantees across Laravel majors. Treat as a "pinned dependency with an internal owner," not a platform component.
• No type safety or key validation. Missing keys fail silently to the raw key string in the UI — a class of bug that surfaces in QA or production rather than at build time.

Key questions to resolve before committing

1. How many translation keys and locales exist today, and how many are actually needed per page/view?
2. Does the app have (or plan) a SPA or mobile client that would need translations outside Blade?
3. Does the package support namespaced and vendor translations, and partial/per-view loading?
4. What is the supported Laravel/PHP version matrix, and how quickly has it tracked major Laravel releases?
5. Is there test coverage for escaping, missing keys, and locale switching?
6. How is the front-end cache keyed today, and who owns changing it?
7. Is runtime locale switching (no reload) a requirement?

Integration Approach

Stack fit

• Assumes Laravel (verify exact version constraints against our current and next major), Blade templating, and a JS layer that does not own its own bundling of translations.
• Composer-only dependency; no Node toolchain changes, no build-step changes. That keeps it out of the front-end release cadence, which is a meaningful operational simplification.

Migration path

• Introduce additively: install, publish config, add the directive to the base layout alongside existing hard-coded strings. Nothing breaks if a page doesn't yet use the JS helper.
• Migrate string-by-string, starting with shared chrome (nav, buttons, form validation, flash messages) where duplication between PHP and JS is highest and value is immediate.
• Retire any existing ad-hoc JSON translation blobs once parity is confirmed, so there is exactly one pipeline.

Compatibility

• Confirm no collision with an existing global __ or with any other i18n/translation package.
• Verify behavior with our caching layer (Redis/view cache/CDN) and with Blade component/layout inheritance, since directives in nested layouts can double-inject.
• Check behavior under @vite/asset versioning and under queue-rendered or PDF/mail views where a script tag is meaningless.

Sequencing

1. Spike (1–2 days): branch install, dump actual serialized payload size for the real lang/ directory across all locales. This single number decides go/no-go.
2. Scoping decision: if payload is acceptable (<~50KB gzipped), proceed with global injection; if not, design per-namespace or per-view loading first.
3. Pilot: one internal, low-traffic page; measure HTML size delta, TTFB, and cache hit rate.
4. Cache-key fix: land locale- and translation-version-aware caching before any user-facing rollout.
5. Conventions + docs: naming rules for keys, rule that client-used keys live in a dedicated namespace, and a lint/test asserting key parity between PHP and JS usage.
6. Broad rollout by surface area, not by locale.

Operational Impact

Maintenance

• Low ongoing cost. The package is stable, the surface is small, and the directive is easy to reason about. Realistic maintenance is a version bump per Laravel major plus occasional config review.
• Assign an internal owner and pin the version. If the package stalls on a future Laravel release, the fallback (a ~40-line Blade directive plus a JSON encode) is trivial to build in-house — this is the key de-risking fact for a TPM to record.

Support

• Community-only, no vendor SLA. Escalation path is: read the source (small), fork, or replace. Budget for that possibility at the architectural level, not the ticket level.
• Onboarding is short: developers already know Laravel's __(), and the JS helper is intentionally identical, so the mental model transfers with near-zero ramp-up (half a day).

Scaling

• Scales with the number of translation keys, not with traffic — but that cost is paid on every request. It is the opposite of a scaling profile most teams expect.
• Mitigations, in order of preference: split keys into namespaces loaded per view; move to a versioned /i18n/{locale}.json endpoint cached at the CDN edge so payload is fetched once per locale and cached in the browser; only then consider a full i18n framework.
• Once the app has more than one client (web + mobile, or a SPA), the HTML-injection model stops scaling organizationally, not just technically — plan the API-endpoint migration as a known future step rather than a surprise.

Failure modes to monitor

• __ undefined in JS after a layout change → client-side errors on every page. Guard with a small shim and an assertion in the base layout.
• Missing keys render raw keys to end users. Add a dashboard/alert on raw-key-shaped strings in production.
• Stale CDN HTML serving the previous locale after a language switch. Test explicitly with two locales behind the cache.
• Encoding breakage on quotes, backslashes, emoji, and RTL strings — include these in the pilot's fixtures.
• Payload regression over time as keys accumulate. Track HTML response size as a monitored metric with an alert threshold.

Ramp-up

• Minimal for any Laravel developer; docs are short and the API is one directive plus one helper. The real ramp-up cost is organizational: agreeing on key naming, ownership, and the caching contract — which is TPM work, not developer work, and should be scheduled as such.