Localization Helpers Laravel Package

Product Decisions This Supports

• Localization roadmap and investment sizing. Clarifies whether adding a locale is a tooling problem (keys missing, files drifting, no repeatable export/import), an engineering-effort problem (locale-aware routes, middleware, URL/canonical/sitemap changes), or a staffing problem (someone must own translation operations). These have very different budget lines; picking the wrong one is the most common localization planning error.
• Build vs. buy vs. adopt. Establishes a low-cost third option between "write an internal Artisan command" and "sign a TMS contract with Crowdin, Lokalise, or Phrase." For a 2–10 locale, developer-owned translation set, adopting a small utility can defer a five-figure annual commitment by several quarters.
• Release quality gate. Supports a concrete, cheap pre-release control: fail CI when a developer adds __('checkout.new_field') to a Blade template and no base-locale key exists. This converts a class of "raw key shown to customer" defects into a build failure — a measurable quality win independent of the package's other merits.
• Locale UX and URL strategy. If the installed version matches its description (locale detection from request/browser, locale switching, locale-prefixed URL/route generation), it informs decisions on example.com/fr/... vs. subdomain vs. query parameter, and whether locale persistence lives in session or cookie. Those are product decisions with SEO and shareability consequences, and they should be made deliberately, not inherited from a helper package.
• Dependency policy for dev-only tooling. Creates a real test case for a standing policy question: are small, single-maintainer, low-adoption packages acceptable for developer-facing, non-runtime utilities? Answering it once removes repeated debate.
• Pilot governance. Supports the decision to run a time-boxed pilot with a pre-agreed abandon criterion, rather than a binary adopt/reject call — the correct posture at 8 stars and 0 dependents.
• Primary use cases supported: scanning application code for translation keys, detecting keys missing across locales, generating/syncing locale files, sorting and cleaning lang/ files, reducing translation-file drift between releases.
• Decision this explicitly does not support: any conclusion about translator workflows, review states, translation memory, or vendor/TMS integration. Those are out of scope and should not be inferred from this package's presence.

PM action before committing roadmap: the supplied material contains two incompatible readings of this package — a runtime localization helper (middleware, locale-aware routing: production surface, needs an ADR) versus a dev-time Artisan command suite (zero production footprint). Treat the discrepancy as a documentation-quality signal and require a 30-minute verification spike (composer show, php artisan list, read src/) before any roadmap item depends on it.

When to Consider This Package

Consider it when:

• The product is a Laravel/PHP application with file-based translations (lang/ or resources/lang/), not JSON-only, database-backed, or CMS-managed strings.
• You manage a small-to-moderate locale set — roughly 2–10 locales — with translations primarily owned by developers, not a dedicated localization team.
• You need lightweight Artisan commands or locale helpers, not a translator-facing platform.
• The BSD-2-Clause license and small command surface fit your dependency policy (attribution/NOTICE obligation is trivial but must be checked for redistribution).
• You are willing to pin an exact version, review the source, and classify it as dev tooling, keeping Git as the source of truth and reviewing generated file changes via pull request.
• Your translation-file hygiene is currently ad hoc — the value here is process discipline as much as code.

Look elsewhere when:

• You need TMS integration, translator assignment/review states, translation memory, or API-based sync. That is a different product category.
• You require enterprise support, SLAs, auditability, compliance guarantees, or a verifiable security disclosure process — none of which exist here.
• You run a large locale matrix or complex pluralization/context rules (ICU MessageFormat, gendered/declined forms).
• An internal Artisan command would be cheaper than the dependency risk — for a narrow command surface, this is often true, and "adopt vs. write 60 lines" is the honest comparison.
• Your dependency policy demands community validation; 8 stars and 0 dependents means the ecosystem has not stress-tested this.
• The runtime reading applies and you already have working locale middleware — the comparison becomes "adopt vs. delete our own 40 lines," not "adopt vs. build."
• You want this in production runtime paths without an ADR and middleware-ordering review.

Adoption criteria if you proceed: install as require-dev, pin exact, run read-only drift detection in CI first, prove lossless round-trip on one real locale (including a non-Latin script and a pluralized string), and only then allow write operations behind human PR review. Assign a named owner and budget a fork as a contingency — the small surface makes a fork days, not weeks, which is the main argument for trying it.

How to Pitch It (Stakeholders)

For executives: This is a low-cost developer productivity utility for Laravel localization workflows. It addresses a specific, recurring release risk — translation keys missing or out of sync across locales, which surfaces as raw placeholder text in customer-facing UI. It is not customer-facing, carries a permissive BSD-2-Clause license with minimal legal exposure, and if installed as a dev dependency adds no production runtime surface. Adoption is very low (8 stars, 0 dependent projects, single maintainer), so the recommendation is a time-boxed pilot with a named owner and an explicit abandon criterion, not immediate standardization. Expected cost is low single-digit engineering days including governance; the realistic outcome is deferring a TMS purchase by two to three quarters while the locale count stays in single digits. Note one open item: the package's description and its release history imply different capabilities, so scope confirmation precedes any commitment.

For engineering: Evaluate on a branch as a require-dev dependency with an exact version pin. First resolve which package this actually is — runtime locale helpers (middleware, route generation; production surface, needs middleware-ordering review and an ADR) or Artisan tooling for key scanning and file sync (zero production footprint). Read src/ and php artisan list, not the README; with this adoption level the code is the documentation. Then start at the lowest-risk, highest-value point: a read-only missing-key drift check in CI (git diff --exit-code lang/ if no dry-run flag exists), which delivers most of the benefit at zero write risk. Validate the oldest Laravel version in the fleet, not just the newest; confirm it honors a non-default lang path and package namespaces; and treat silent skipping of unrecognized key shapes (dynamic keys, pluralization pipes, :placeholder handling, vendor namespaces) as a defect rather than a limitation. Any command that rewrites lang/ is destructive against assets with almost no test coverage — gate every mutation behind reviewed pull requests, never run writes on a protected branch, and keep Git as the rollback mechanism.