Langsys Php Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy for localization infrastructure. This package is the Laravel-side integration for a hosted translation catalog (Langsys). It lets you skip building locale negotiation, catalog registration, and retrieval plumbing yourself, at the cost of a SaaS dependency. That is the core trade to weigh.
• Market-expansion roadmap sequencing. DetectLocale (query → cookie → session → Accept-Language, canonical BCP 47) plus a shared catalog across PHP and JS means adding a locale is a catalog/config exercise rather than an engineering project — a real input to how many markets you can commit to per quarter.
• Frontend architecture decisions. t()/@t with params passed to the SDK keeps one catalog entry per phrase (Welcome {name}) rather than one per runtime value. That materially changes catalog size, translation cost, and QA surface — worth factoring into how you scope i18n work.
• SSR vs. client-rendered i18n. InertiaSsrProps::share() seeding initialTranslations determines whether you can ship SSR-first Inertia apps without a flash of untranslated content. If your roadmap includes Vue/React/Svelte with Inertia SSR, this unblocks it.
• A genuine product-risk decision: tagged mode vs. automatic mode. Automatic mode (TranslateResponse) covers everything, including text Alpine injects from JS expressions that @t structurally cannot reach — attractive for legacy or content-heavy pages. But the release is explicit that running both modes pollutes the shared catalog with already-translated strings. This is a per-project policy decision that must be made once and enforced, not left to individual developers.
• Where to spend localization effort. Automatic mode is a lever for "translate the long tail without tagging every string," which is a scoping decision for teams that cannot afford a full string-extraction pass.

When to Consider This Package

Consider it when:

• You are on Laravel 10, 11, or 12 with PHP 8.1+ and have a real, funded multi-locale roadmap rather than a single-locale app.
• You are already using or willing to adopt Langsys as your translation catalog. This is a client/integration, not a translation platform — it does not replace your TMS, vendor, or review workflow.
• You have Blade and/or Inertia (Vue/React/Svelte) frontends and want one catalog serving both server and client rendering.
• You run Octane or other long-lived workers — FlushPendingRegistrations with an Octane listener is explicitly handled, which is the failure mode most i18n packages get wrong.
• You value fail-open behavior: lookups degrade to the base-language phrase with interpolation intact, registrations never break requests or workers, and automatic mode serves the untranslated page rather than a blank body.

Look elsewhere — or defer — when:

• ext-intl is not available in your runtime. This is a hard requirement, and the official php:8.x-fpm images do not include it. If you cannot change base images or add the extension, this is a non-starter regardless of merit.
• You need a non-Langsys translation provider, a self-hosted/air-gapped translation memory, or contractual SLAs and a long production track record. This is v1.0.0 — the first release, with known gaps documented in the ROADMAP. Treat it as an early-adopter bet.
• You cannot enforce a per-project mode policy. The "never both" constraint is a real operational hazard; teams that let developers freely choose tagged vs. automatic will corrupt a catalog shared across every Langsys SDK.
• You are single-locale, or your localization needs are satisfied by Laravel's built-in __() and language files.
• Your JS-side version is below langsys-js-typescript 0.6.2 — SSR plus hydration requires that floor, so pin and verify.

How to Pitch It (Stakeholders)

To executives: This is a thin, low-integration-cost Laravel layer over a hosted translation catalog — one composer require, one shared catalog serving both PHP and JS. It shortens the path from "we want to enter market X" to "market X is live," and it is deliberately fail-safe: a translation outage degrades to the base language rather than breaking pages or blanking responses. The trade is a vendor dependency on Langsys plus a small infrastructure change (ext-intl in our PHP images). Recommendation: pilot on one locale expansion, measure tagging effort and catalog coverage, then decide on wider rollout.

To engineering: The Laravel-native surface only — t()/@t, DetectLocale, FlushPendingRegistrations (Octane-aware, post-response), opt-in TranslateResponse, and InertiaSsrProps::share(). The underlying SDK is dependency-free, so there is little to audit beyond the wrapper. Design decisions favor degradation over exceptions throughout. Two things to own explicitly: (1) ext-intl must be added to our base images, and (2) we must pick tagged or automatic mode per project and document it — running both re-registers translated strings as source phrases and pollutes the catalog for every consumer. Use translate="no"/data-notrans to carve out resolved subtrees.

Known risks to state openly: v1.0.0 maturity, SaaS coupling to Langsys, the mode-policy foot-gun, and the ext-intl infrastructure prerequisite. None are blockers for a scoped pilot; the first two argue against committing the entire localization strategy on day one.