Json Fallback Hotfix Laravel Package

Product Decisions This Supports

• Localization roadmap / market expansion: Shipping a new locale with partial translation coverage is normally gated on 100% string completion, because any missing JSON key renders as a raw string like auth.failed in the UI. This package decouples "launch the locale" from "translate every string," letting you ship a locale at, say, 70% coverage on a proven fallback locale and close the gap post-launch. That directly compresses the timeline for entering a new market.
• User-visible quality and support load: Raw translation keys leaking into the interface are a high-visibility, high-embarrassment defect class that generates support tickets and store reviews disproportionate to their actual severity. A drop-in fix removes that defect class from the backlog rather than scheduling recurring QA and hotfix work around it.
• Build vs. buy: The alternative is an in-house override of Laravel's translator/JSON loader — a small piece of code with an outsized maintenance tail, because it touches framework internals and must be re-validated on every Laravel upgrade. Adopting a 1-line Composer dependency with an MIT license is the cheaper, lower-risk option unless you already have a translation platform that solves the same problem.
• Framework upgrade planning (Laravel 13): Release 2.3.0 declares Laravel 13 support. That's a green light for the roadmap item "upgrade to Laravel 13" — this dependency is not a blocker, so it shouldn't appear on the upgrade risk register as one.
• Prioritization signal for content operations: Once fallback is reliable, you can instrument and measure fallback hit rate per locale. That turns "how translated is German?" from a gut call into a metric, and gives you an evidence-based trigger for funding the next translation batch versus deprioritizing it.
• Risk acceptance decision: With 16 GitHub stars, this is a small, single-maintainer package. That is a real (if modest) product risk. The PM decision is whether a narrow, well-scoped, MIT-licensed fix in a widely used ecosystem is acceptable — generally yes for a non-critical rendering path, but it belongs in the dependency risk register rather than being adopted silently.

When to Consider This Package

Adopt when:

• The app serves multiple locales and uses Laravel's JSON translation files (lang/*.json) rather than only PHP array files.
• Locales are partially translated, or will be during rollout — i.e., there's a realistic chance a key is missing in the active locale.
• A fallback locale is configured and that fallback is meaningfully complete (typically English).
• You want a zero-config, zero-migration fix: no database changes, no changes to existing lang/*.json files, no changes to developer translation workflow.
• You're on or moving to Laravel 13 and want to pin ^2.3 so installs don't resolve to a release that excludes your framework version.

Look elsewhere when:

• You use only PHP array-based language files. Native Laravel fallback already behaves correctly there; this package adds a dependency for no benefit.
• You're single-locale. No fallback path exists to fix.
• You need translation workflow features — missing-key dashboards, translation sync with a TMS, ICU/pluralization handling, per-string review states. This is a runtime behavior hotfix, not a translation management product; evaluate a dedicated platform instead (and note that a database-driven translation loader may make this package redundant or conflicting).
• You need vendor support, SLAs, or audited provenance. MIT and community-maintained means no commercial backing; for regulated or high-availability contexts, budget for the option of reimplementing the fix internally.
• Laravel ships an upstream fix. The package is explicitly a hotfix for a framework gap. Watch release notes: if the behavior is corrected natively, this becomes a removable dependency, and you should plan its retirement rather than let it calcify.
• The maintainer goes inactive and a future Laravel major breaks it silently — the fallback path is unlikely to be covered by your test suite unless you deliberately test it.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our multilingual experience has a known defect: when a string hasn't been translated for a given language, users see a raw internal key instead of readable text. That's visible, embarrassing, and generates support contacts out of proportion to its technical severity, and it currently forces us to fully translate a language before we can launch it — slowing market expansion. This package is a one-line, MIT-licensed, zero-configuration fix that makes missing translations display our fallback language instead. It requires no database or infrastructure change, no redesign of our translation workflow, and it's already compatible with our planned Laravel 13 upgrade. Cost is effectively zero; the return is a cleaner product surface and the ability to launch new languages incrementally instead of all at once.

For engineering (the short version): Drop-in Composer dependency; no service-provider config, no migrations, no publish step, no changes to existing lang/*.json. Pin ^2.3 — that release adds the Laravel 13 constraint and CI lane, so it's the minimum for a Laravel 13 app and it keeps us from resolving to an older release. Semver minor over 2.2.x with no API or extension-point changes, so the upgrade itself carries near-zero code risk; the real risk is transitive dependency resolution during the framework bump, not this package. Two asks: (1) add an integration test asserting fallback behavior on a key we know is missing in a secondary locale, so an upstream Laravel fix or a future package break is caught rather than discovered in production; (2) add it to the dependency risk register as a small, single-maintainer dependency with a defined exit path — removal if Laravel fixes it natively or the maintainer goes inactive. Rollout is standard: install in staging, confirm behavior, then promote with rollback to the prior version available.