Json Fallback Laravel Package

Product Decisions This Supports

• Localization rollout sequencing. Lets you ship a market before its translation coverage is 100% complete. Because missing JSON keys resolve from a fallback locale rather than rendering blank or raw keys, "translation completeness" stops being a hard release gate and becomes a tracked quality metric. This is the core decision it unlocks: can we launch locale X on date Y with N% coverage?
• Build vs. buy on fallback logic. The alternative is bespoke resilience: ?? 'fallback' guards in Blade, defensive lookups in JS, or a custom JsonLoader. That logic tends to sprawl across frontend and backend, is untested, and breaks silently. This package replaces it with a framework-native swap in a service provider. Decide to buy unless you need multi-tier fallback chains or nested JSON structures — both of which require extending it anyway.
• Release readiness criteria. Separates product readiness from content readiness. Releases no longer block on translation vendor turnaround, and translation updates can ship in their own cadence without a code deploy.
• Prioritizing translation spend. Fallback hits are a direct signal of localization debt. Instrumenting "which keys fell back, in which locale, how often" turns an unquantified cost ("we should translate more") into a ranked backlog: translate the keys that fall back in checkout before the ones that fall back in a settings tooltip.
• A localization health KPI. Define fallback rate (percentage of rendered strings served from the fallback locale, per locale, per surface) as the north-star metric for international expansion. It's leading-indicator-ish, cheap to instrument, and directly actionable by both product and content teams.
• Architecture direction: JSON translations. If the roadmap includes SPAs, mobile clients, or API-delivered UI copy, JSON translation files are the natural substrate and native Laravel fallback does not cover them. Adopting this package is a small, reversible bet in that direction.
• Risk posture on dependencies. Weigh honestly: MIT licensed, Laravel Lang community stewardship, releases tracking Laravel 11/12/13 — but ~16 stars, zero dependents, and effectively a single maintainer. Verdict: low integration risk (small surface, easy to fork or vendor), non-trivial continuity risk. Fine for a contained capability, not something to build a translation platform on top of without a fallback plan of your own.

When to Consider This Package

Adopt when:

• Your UI copy lives in JSON translation files (lang/{locale}.json) — SPA/hybrid frontends, API-supplied strings, JS error messages, dynamic labels — and you have no fallback today.
• You want a single, predictable fallback locale (e.g., fr → en) resolved server-side, so no frontend code needs to know about it.
• Your stack is Laravel 10–13 on PHP 8.1+, and you want zero changes to controllers, views, or existing __() / trans() call sites.
• You support 3+ locales with uneven coverage and no dedicated localization engineer — the maintenance argument dominates.
• You're actively migrating from PHP arrays to JSON files and want the fallback story solved before the migration, not after.
• You can add JSON linting/validation to CI. Malformed files undermine any fallback guarantee, and the package won't save you.

Look elsewhere when:

• Your translations are PHP-array-based. Native Laravel fallback already handles this; the package adds nothing.
• You need multi-level chains (pt-BR → pt-PT → en). Out of the box it's one tier; anything richer is custom work.
• Your JSON is nested or non-flat, or values are objects/arrays. Key flattening becomes your problem to solve and document.
• You need database-backed or remotely managed translations (spatie/laravel-translation-loader, Crowdin/Lokalise runtime delivery). Those vendors usually ship their own fallback semantics; integrating both is duplicated logic.
• You rely on runtime locale switching with per-user rules beyond a single configured fallback.
• You're on Laravel <10 / PHP <8.1.
• You require a commercially supported or widely adopted dependency. Zero dependents means you are, functionally, the first production user — budget for reading the source.

How to Pitch It (Stakeholders)

Executives (30 seconds). When a translation is missing in a launched market, users don't see an error — they see a blank button, a raw key like checkout.submit, or an empty label. That happens in the highest-value flows and it costs conversions quietly, without a support ticket. This package makes missing translations degrade gracefully to English instead of breaking the interface.

The ask is small: roughly a day of engineering, no licence cost, no vendor contract, and it's reversible. The strategic value is that translation completeness stops being a launch blocker. We can enter a market on schedule at 80% coverage, measure exactly which strings are falling back and how often, and spend translation budget where it actually costs us money rather than where a spreadsheet says we're incomplete. Whether this reduces support volume or lift is a hypothesis we should test in one flow before generalizing — I'd want the fallback-rate dashboard live before we make that claim externally.

Engineering (the working agreement). The integration is a service provider that swaps Laravel's JsonLoader for a fallback-aware one. No changes to controllers, Blade, or existing __() calls. Configuration is a fallback locale. Cost is a file lookup on miss — negligible, but worth a quick benchmark against your largest JSON file.

The constraints to accept up front: flat keys only, single fallback tier, JSON files must be valid. If we need nested keys or pt-BR → pt-PT → en, that's our work, not the package's — estimate it before committing rather than discovering it mid-migration.

The dependency risk is real but bounded. Small surface area, MIT, one active maintainer. Mitigations: pin a version, vendor or fork it if maintenance lapses (a day's work given the scope), and keep fallback behaviour behind a single config point so it can be replaced.

Proposed sequence: (1) add JSON validation to CI so we can trust the files at all; (2) pilot in one revenue-critical flow in one locale; (3) instrument fallback hits and ship the per-locale, per-key report; (4) expand only if the data supports it. Do not roll this out globally before step three — the measurement is the point.