Translator Laravel Package

Product Decisions This Supports

• Build vs. buy (translation layer): The package stays deliberately thin — file-convention based, no new storage format, no migration burden. That makes it a credible "don't build it" answer for teams whose i18n needs are flat key→string lookups, and keeps budget focused on product differentiators rather than a homegrown translation helper.
• Localization roadmap sequencing: has() and all() are the enablers for the work that usually comes after a translation helper — missing-key audits in CI, coverage dashboards ("what % of keys are translated per locale?"), and admin/ops tooling to inspect loaded strings. This lets you sequence "localization maturity" as a roadmap item without a rewrite; the inspection primitives now exist.
• Frontend/API delivery decisions: Array loading turns the package into a viable source for bulk translation bundles (hydrating JS or serving a locale payload from an endpoint) instead of one-key-at-a-time round trips. That's a performance and architecture input for any SSR/SPA decision touching copy.
• Release quality and risk posture: The falsy-value fix (empty string, 0, false no longer falling back to the key) is a correctness fix, not a feature. Product-side this matters: intentionally blank labels, numeric strings, and boolean-ish feature copy were silently rendering raw keys in production. Treat this as a bug-fix justification for a patch/minor upgrade, not as scope.
• Content-authoring workflow: Placeholder replacement inside translate() removes sprintf/concatenation at call sites. That reduces a common class of localization defects — broken word order in non-English locales and mismatched argument counts — and makes strings handed to translators self-contained and reorderable.
• Runtime support matrix as a constraint: Tests pass on PHP 7.1 through 8.5. This supports a "upgrade independently of PHP upgrades" decision: you can adopt the package now on a legacy monolith and still carry it forward through a framework/runtime modernization.
• Evidence caveat for the decision record: No quantitative data (usage, defect rates, dependency footprint, maintainer activity) was supplied with this release. This assessment is derived from release notes only. Before committing roadmap dependencies to has()/all()-based tooling, request: test coverage report, issue-tracker activity, semver history, transitive dependency list, and confirmation that the falsy-value change is non-breaking for existing lang files.

When to Consider This Package

Consider it when:

• You're on Laravel (or plain PHP) with existing PHP-array language files and want helper ergonomics — placeholders, bulk load, key inspection — without changing your file convention or migrating content.
• You have legacy runtime constraints (PHP 7.1+) and need one translation dependency that spans old and new PHP versions.
• You want a minimal, low-lock-in dependency for a small-to-mid product surface where i18n is a feature, not the product.
• You need programmatic introspection of translations for CI guards or internal tooling, and don't want to hand-roll a key scanner.
• You're doing a low-risk incremental upgrade and the falsy-value behavior change is acceptable (i.e., nothing downstream depended on falsy values falling back to keys — verify this, since it's the one behavior change with blast radius).

Look elsewhere when:

• You need ICU MessageFormat, plurals, gender, or number/date formatting — this is key→string substitution, not a message-formatting engine; use Symfony's ICU support or an established i18n library.
• Copy is owned by non-engineers and needs a TMS workflow (Crowdin, Lokalise, Phrase) with review states, screenshots, and translation memory.
• You need database- or API-backed translations, per-tenant overrides, runtime editing, or cache warming with invalidation (look at spatie/laravel-translation-loader, Laravel Langman, or a CMS-backed approach).
• You need locale negotiation, route-level locale switching, pluralization rules, or fallback chains beyond a single missing/null fallback.
• You're serving client-side bundles at scale and need compiled, tree-shaken, versioned asset output — array loading is necessary but not sufficient.
• Maintainership is a concern and you can't get answers on release cadence, security response, or the PHP 7.1 EOL posture. Supporting 7.1 is good for you tactically, but it also signals a maintenance surface that includes EOL runtimes; don't read it as a recommendation to stay on 7.1.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a small, low-cost upgrade to our translation layer with no migration work and no change to our existing language files. It fixes a correctness bug where intentionally blank or numeric copy was silently rendering raw keys to users, adds placeholder support so translated sentences stay grammatically correct in other languages, and exposes the inspection hooks we'd need for a future translation-coverage dashboard. It runs across our current and future PHP versions, so it doesn't couple to our platform upgrade timeline. Risk is low and contained; the one thing to verify is that no code relied on the old fallback behavior.

To engineering (the ask): Minor-version upgrade, expected to be drop-in. Two things to check before merge: (1) confirm nothing depends on falsy values falling back to the key — the release changes empty string, 0, and false to be treated as valid translations; (2) confirm existing lang-file structure is untouched, since the release explicitly preserves the current convention. Then adopt the new surface deliberately: placeholders in translate() to replace sprintf at call sites, array loading for bulk/frontend payloads, and has()/all() as the basis for a CI missing-key check. Return with test coverage numbers and dependency/semver history so we can size the bet on building internal tooling on top of has()/all().