Localization Laravel Package

Product Decisions This Supports

• Market-expansion sequencing. A localized subdomain (fr.example.com) is the cheapest credible test of "is market X worth funding?" This package reduces the engineering half of that test to days, so the conversation shifts from sprint capacity to content and go-to-market budget — which is the right framing for deciding which markets we open and in what order.
• URL architecture: subdomain vs. subdirectory vs. header/cookie. This is the real decision the package forces, and it is expensive to reverse after launch. Subdomains give clean per-market roots, simple hreflang, and per-locale edge caching; they complicate shared sessions, cookie scoping, wildcard TLS, and any existing subdomain-as-tenant convention. A PM should treat evaluating this package as evaluating that trade-off, not as evaluating a Composer dependency.
• Roadmap scoping: plumbing vs. content. Adopting it commits us only to locale resolution and routing. The larger bets — translation memory, per-locale content workflow, translated slugs, localized marketing copy — stay independent line items. This lets us fund the cheap half of i18n now and keep the expensive half gated on the pilot's results.
• Adopt vs. vendor as the build/buy question. The code surface is small enough that "buy" and "build" cost roughly the same in engineering hours. The genuine decision is dependency governance: a two-star, single-maintainer package with zero dependents fails most intake scorecards, but its BSD-2-Clause license makes forking or vendoring essentially free. That converts the decision from "trust upstream" to "own ~200 lines," which is a decision a PM can actually shepherd.
• Pilot gating with defined success metrics. Best used as a flagged experiment for one locale with a measurable criterion (organic sessions, signup rate, conversion in-market) rather than as platform infrastructure. That gives us a clean kill/scale decision at the end of a defined window.
• Marginal cost of the next market. Once in place, opening a geography becomes DNS + config + content rather than an engineering project. That is a strategic asset worth putting in roadmap conversations about speed of geographic expansion.
• Dependency-risk scoring input. The package's own description in circulation is inconsistent with what the code does (localized Eloquent attributes vs. subdomain routing). For a PM that is a documentation-quality flag on par with the star count: if we cannot tell from the artifact what it does, we cannot scope a roadmap item on it without a verification spike.

When to Consider This Package

Consider it only when all of the following hold:

• You are on Laravel 11/12 or can pin to ^2.0.4, the Laravel 12-compatible line. Older framework versions are a different conversation.
• Subdomain-per-locale is the architecture you actually want. The package resolves locale from the Host header. If your target is /fr/ subdirectories, translated route slugs (/fr/a-propos), or Accept-Language negotiation, this is the wrong tool — reach for mcamara/laravel-localization or write the middleware yourself.
• You are running a bounded pilot, not committing the platform. One market, one subdomain, one measurable outcome. Budget the exit: the middleware is 30–60 lines and can be replaced in an afternoon.
• You accept ownership of the source. Two stars, zero dependents, one maintainer, a thin README, and documentation that contradicts itself about what the package does. Plan to vendor it into app/Packages/localization, pin the upstream commit, and add your own tests. BSD-2-Clause permits this; the cost is roughly a day, and it turns a bus-factor-one dependency into an owned component.
• You can answer the product questions the package leaves open: apex-host behavior (301 to en. vs. serve default vs. 404), per-locale canonical and hreflang strategy, session cookie scope across subdomains, and precedence against any existing session- or cookie-based language switcher.
• You have wildcard TLS and CDN/TrustProxies configuration under control. Locale is derived from a client-supplied header; getting the proxy layer wrong silently breaks locale resolution behind the edge.

Look elsewhere — or budget a sprint to build it — when:

• You need translated route slugs, Accept-Language negotiation, or per-user locale preferences. None are in scope.
• You need database-driven translation management (admin UI for copy editing, import/export of lang/ files). The package description in circulation advertises this; the code in this tag is subdomain routing. Verify against the actual middleware before scoping either feature.
• Subdomains conflict with an existing tenancy or routing convention. Retrofitting subdomain localization onto a product that already uses subdomains for customers is a migration, not an adoption.
• Procurement or security review rejects single-maintainer dependencies outright. In that case, skip to the fork and treat it as internal code from day one.
• You are already standardized on mcamara/laravel-localization. Both packages have historically shipped a LaravelLocalization alias; running both produces a fatal conflict for no benefit.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: We can test a new geographic market for roughly a sprint of engineering instead of a quarter, using a small open-source Laravel component that routes fr.example.com-style subdomains to the right locale. The package is a two-star, single-maintainer dependency, so we will not depend on it — we will vendor roughly 200 lines under our BSD-2-Clause rights and own them. That reduces the ask to: fund one locale pilot with a defined success metric, and treat the go/no-go on the second market as a content and marketing decision rather than an engineering one.

For engineering — the ask and the shape of the work:

• Pin torann/localization:^2.0.4, publish the config, read the middleware and service provider before writing any application code. The entire package is auditable in an afternoon; do that audit as task one.
• Register the middleware in bootstrap/app.php after TrustProxies. Validate the resolved locale against the config allowlist before it reaches any redirect, cache key, or URL::defaults() call — an unvalidated locale segment feeding redirect() is the plausible open redirect in this design.
• Set URL::defaults(['locale' => app()->getLocale()]) once, or every route() call outside an HTTP request will silently emit the wrong host. This is the single highest-value line of glue.
• Audit route() calls reachable from queued jobs, scheduled tasks, console commands, and mailables rendered in workers — there is no request host in those contexts, so URLs fall back to APP_URL.
• Carry locale explicitly on job and mailable payloads; never let a worker inherit it. Verify the middleware sets locale per-request, not per-boot, before enabling Octane.
• Run php artisan optimize in CI. Dynamic domain parameters plus cached routes plus cached config is the combination that breaks quietly.
• Write three feature tests in week one against full hosts — subdomain resolves locale, apex host does the documented thing, unknown locale 404s — and one that sends Host: evil.example.com and asserts a 404, not a redirect.

Decisions we need from product before build starts: apex-host behavior, session cookie domain (.example.com shares the session across all locales — confirm that is intended), canonical and hreflang ownership, and whether the subdomain or an existing switcher wins when both try to set locale. The package answers none of these; we should not discover them in production.

What we are explicitly not buying: translation management, translated slugs, language negotiation, and content workflow. Those remain separate roadmap items, gated on whether the pilot works.