Laravel Localizer Laravel Package

Product Decisions This Supports

• Internationalization roadmap sequencing: gives concrete answers on what it costs to add locale N. Because a locale is defined by a config entry plus generated assets, PMs can reason in "one config block + one CI step + translation content" units rather than open-ended engineering estimates — useful when deciding whether to ship 3 locales or 12 this quarter.
• Build vs. buy for the translation delivery layer: the honest baseline is "a small internal script that dumps lang/ to JSON and emits a .d.ts." This package is that script, productized. The decision is therefore less "build vs. buy" and more "adopt a 7-star, single-maintainer dependency vs. own ~200 lines of glue." PMs should treat it as a low-cost experiment, not a platform commitment.
• Frontend architecture decisions: it pushes a specific answer to "where do translation strings live in an SPA?" — build-time generation into TypeScript instead of runtime JSON fetches. That is a real product decision (faster first paint, no locale-fetch waterfall) and this package makes the typed-build-time option cheap to try.
• Type-safety as a quality gate: generated as const TypeScript means missing/renamed keys fail the frontend build rather than surfacing as raw keys to users. PMs can convert "translation coverage" from a manual QA checklist into a CI signal — a measurable reduction in a class of user-visible bugs.
• Market entry for RTL locales (Arabic, Hebrew, Farsi): first-class dir metadata plus Inertia-shared locale props means RTL support is a config change, not a UI rewrite. Relevant when deciding whether an RTL market is reachable with the current design system.
• Prioritizing markets with machine translation as a stopgap: localizer:translate lets you ship a locale for SEO/discovery or a beta cohort before funding human translation. PMs can decouple "locale is live" from "locale is professionally localized" — but only with explicit quality guardrails (see risks below).
• Locale detection/UX decisions: the middleware's documented precedence chain (query → header → session → user model → Accept-Language → default) is a ready-made product policy. PMs should ratify or override it consciously (e.g., should a logged-in user's saved locale always beat a ?locale= param?) rather than inheriting it by default.
• Not supported: pricing/packaging per region, content marketing localization, legal/compliance translation workflows, translator-facing operations. This is an engineering delivery tool, not a translation management system.

When to Consider This Package

Consider it when most of these are true:

• Stack is Laravel 11/12 + PHP 8.4+, with a React/Vue/Inertia SPA frontend — ideally already on Inertia, where the shared locale props do real work.
• The team is small and no dedicated i18n platform (Phrase, Lokalise, Crowdin) is in place; strings currently live in lang/ and reach the frontend via ad-hoc JSON endpoints.
• You want typed translation keys and are willing to add a build-time codegen step to CI.
• You are adding a small number of locales (roughly 2–6) and can absorb the full string surface in-house.
• Someone on the team can read the source and fork it if needed — the codebase is small and MIT-licensed.
• You want to run a bounded pilot: one locale, one release cycle, with a defined rollback (delete the dependency and the generated files).

Look elsewhere / do not adopt when any of these are true:

• Production-critical, multi-year commitment with no internal PHP capacity. 7 stars, 0 dependents, a single named maintainer, and no external production references is the entire risk profile. There is no adopter base to inherit bug fixes or security review from. Budget the fork as a first-class option before adopting.
• You need an actual TMS: non-technical translators, review/approval workflows, translation memory, glossary enforcement, per-string context, vendor management. This package has none of that and never will.
• You need ICU MessageFormat: plural/gender/select logic beyond the frontend packages' stated pluralization support should be verified against your worst-case strings before committing. Complex plural rules (Polish, Arabic, Russian) are the classic place homegrown i18n breaks.
• Auto-translate is central to your plan. The Google Translate integration depends on an unofficial scraping library (stichoza/google-translate-php). That carries ToS/reliability risk, and raw MT output is not acceptable for brand copy, legal text, or safety-relevant UI. Treat MT as internal scaffolding for unreviewed locales only, gated by a review flag.
• Non-Laravel backend, or Next.js/Nuxt with an existing i18n stack (next-intl, i18next, @nuxtjs/i18n). You would be duplicating a solved problem with a less-adopted tool.
• You need vendor support, SLAs, security advisories, or a procurement-friendly dependency — this will not survive a security questionnaire in a regulated environment.
• Release/versioning discipline is a requirement. Treat the "last release 2026-10-30" date as a data-quality flag rather than evidence of a healthy cadence; verify against the actual tag history and changelog before relying on a maintenance signal.

Deployment cost PMs must budget for: localizer:generate --all becomes a mandatory pre-build step (generated files are gitignored by the installer). That is a new failure mode in CI and a new step in every environment bootstrap — small, but real, and it must be owned.

How to Pitch It (Stakeholders)

To executives — one paragraph: "This is a small, free, MIT-licensed add-on that closes a specific gap: our Laravel backend owns translations, but our React/Vue frontend currently reaches them through hand-rolled JSON endpoints with no type checking. Adopting it gives us typed translation keys that fail the build instead of reaching customers, adds RTL support as a config change, and cuts the marginal engineering cost of launching a new locale to roughly a config block plus a CI step. It is low cost and reversible — we can remove it in a day. The risk is not technical, it's dependency risk: the project is early-stage with a single maintainer and no known production users, so we should adopt it behind our own thin wrapper, pin the version, and keep a one-day fork path. I recommend a one-locale pilot, not a platform decision."

To engineering — the framing they will want:

• Small surface area, MIT, readable source; we can vendor or fork it without drama.
• Replaces ad-hoc translation endpoints with build-time codegen; removes a runtime fetch from the critical path and makes keys type-safe via generated as const modules.
• Standard Laravel conventions: config publish, middleware, Artisan commands, facade. Onboarding cost is low and it does not restructure lang/.
• Non-negotiables we should impose: pin the version, wrap the facade and middleware behind our own thin adapter so we can swap the implementation, verify pluralization and placeholder handling against our worst-case strings before rollout, run localizer:generate in CI pre-build with a drift check, and keep MT output behind an explicit "unreviewed" gate.

To the localization/content stakeholders: This does not replace your TMS or your translators — it changes where strings are stored and how the frontend consumes them. Expect the lang/ files to remain the source of truth; machine translation is available as internal scaffolding only and must not be published to customer-facing locales without review.