Json Fallback Laravel Package

Technical Evaluation

Architecture fit

• Narrow, surgical scope: this package only changes behavior for JSON translation files (lang/{locale}.json), replacing Laravel's default JSON loader with one that resolves missing keys against a configured fallback locale. PHP array translations are untouched — Laravel's native fallback already covers those.
• That precision is the main architectural selling point. It fits services where user-facing copy is shipped as JSON to SPAs, mobile clients, Blade-rendered dynamic strings, or API error payloads — i.e., architectures where the frontend consumes __() output but has no way to compute a fallback itself.
• It is not an i18n platform. It does not manage catalogs, does not touch DB-backed translation providers, and does not implement multi-tier locale chains (fr-CA → fr-FR → en). If our i18n design assumes tiered fallbacks or provider-based loaders, this package is a partial fit at best.

Integration feasibility

• Low effort by design: Composer install plus service-provider registration; no controller, Blade, or view changes. The public API surface we call (__(), @lang, trans()) stays identical, which keeps blast radius small and makes a pilot cheap (~a day including validation).
• The real integration work is data hygiene, not code: flat-key JSON files, consistent key naming, and CI validation to catch malformed JSON before deploy. That is a process cost a TPM must budget for, not a library cost.
• Interacts with Laravel's translation cache — cache invalidation during deploys needs to be confirmed in staging, particularly if fallback locale config changes at runtime.

Technical risk

• Concentration risk is the headline. 16 stars, 0 dependents, single-maintainer lineage (andrey-helldar), and history as a hotfix fork (json-fallback-hotfix). This is a bus-factor-1 dependency with effectively no ecosystem signal. Mitigant: MIT license plus a tiny, well-bounded code surface — we can vendor or reimplement in an afternoon if the project stalls. That, more than the star count, is what makes the risk tolerable.
• Versioning risk: the 2.0.0 release renamed both package and namespace (breaking). Combined with major-version bumps tied to Laravel majors (11 → 12 → 13 landed as 2.1.0 / 2.2.0 / 2.3.0), we should expect a mandatory dependency upgrade on every Laravel upgrade and budget for it.
• Behavioral risk: silent fallback can mask translation debt. Without instrumentation, missing keys become invisible and coverage silently degrades. Mitigate with a metric (fallback hit rate per locale per key), otherwise the business case is unmeasurable.

Key questions

1. Do our JSON translation files use flat keys, or nested objects requiring preprocessing?
2. Is a single-tier fallback sufficient, or does the product require regional chains?
3. Does anything else in the stack override JsonLoader (e.g., a DB-backed translation provider, Inertia/SPA translation pipeline) that would conflict?
4. On which Laravel major do we target, and does this package's supported matrix cover it at ship time?
5. Do we have JSON linting + key-parity checks in CI today? If not, who owns adding them?
6. Who is our named owner and succession plan for a single-maintainer dependency?

Integration Approach

Stack fit

• Qualifies if: Laravel 10–13, PHP 8.1+, JSON-based translations in use, and a single sensible fallback (typically en) is acceptable.
• Disqualifies if: translations are PHP-array-based (native Laravel fallback already solves it), you need multi-level chains, you use a third-party translation loader, or your JSON values are nested objects rather than flat strings.
• Fit is strongest for greenfield localization rollouts and JSON-first frontends; weakest for mature apps with a custom translation provider already in place.

Migration path

1. Inventory — enumerate JSON locale files, count keys, measure parity against the source locale. This baseline is both the business case and the post-rollout success metric.
2. Normalize — flatten nested keys, enforce a single casing/naming convention, add jsonlint (or equivalent) to CI.
3. Configure fallback — set the fallback locale in config/app.php; confirm it matches product intent, not just a default.
4. Pilot — one non-critical surface first (e.g., marketing or settings pages), then a high-impact flow (checkout/auth) once behavior is verified.
5. Instrument — log fallback resolutions with locale + key so translation gaps become a backlog instead of an invisible defect.
6. Roll out — enable globally; remove any bespoke ?? 'default' fallback code found in Blade/JS during step 1.

Compatibility

• Pin the package version to the Laravel major in use; treat this as a coupled upgrade, not an independent one.
• Validate coexistence with any translation cache warmer/lang:publish tooling and with any package that decorates the translator.
• Confirm behavior for JSON files that exist but are empty, and for locales with no JSON file at all — both are common real-world states during incremental rollouts.

Sequencing

• Do this before adding locales 4+, not after. The cost of custom fallback logic grows with each locale, and this package's value is highest as an enabler of the next market launch rather than as remediation.
• Run it as a two-sprint workstream: sprint 1 = audit + CI validation + pilot; sprint 2 = instrumentation + full rollout + legacy-hack cleanup.
• Do not bundle it with a Laravel major upgrade; sequence it after the framework upgrade stabilizes so failures aren't ambiguous.

Operational Impact

Maintenance

• Ongoing cost is low in code but non-zero in process: dependency bumps on each Laravel major, JSON key hygiene in CI, and ownership of the fallback locale configuration.
• Bus-factor mitigation should be decided up front: (a) accept and monitor, (b) fork and vendor internally, or (c) replace with ~50 lines of custom loader. All three are viable given the small surface; leaving it undecided is the actual risk.
• License is MIT — no procurement, legal, or vendor-lock-in overhead. Composer-native, so it fits existing dependency governance.

Support

• No commercial support; the Laravel Lang community and GitHub issues are the only escalation path. For a package of this surface area that is acceptable, but it must be reflected in the on-call runbook.
• Translation-quality incidents (wrong string shown, English leaking into a localized UI) are no longer backend incidents — they become content/translation-team incidents. Clarify ownership in the support model, otherwise fallbacks get triaged as bugs by engineering.
• Document the fallback locale and its rationale in the localization runbook; this is a config value with product consequences that is easy to silently change.

Scaling

• Performance cost is a per-lookup map check — negligible against JSON translation load times, but worth a benchmark if catalogs are large or lookups are hot. No new infrastructure, no DB, no external service: this scales linearly with traffic like the rest of Laravel's translator.
• Scales well organizationally: it removes per-locale custom fallback code, which is where localization technical debt usually accumulates as you add markets.
• Does not scale to complex locale topologies. If the roadmap includes regional variants (pt-BR/pt-PT, zh-Hans/zh-Hant with chains), plan for a wrapper or a custom loader now rather than retrofitting later.

Failure modes

• Silent degradation — fallbacks fire constantly and nobody notices that a locale is 40% untranslated. Highest-probability failure; mitigated only by instrumentation and a coverage dashboard.
• Malformed JSON in deploy — a bad locale file breaks fallback resolution for that locale. Mitigated by CI validation.
• Package abandonment — no updates for a future Laravel major. Detectable early (the maintainer has consistently shipped support within a release cycle); response is fork/vendor, which is cheap here.
• Overridden loader conflicts — another package or a custom provider also decorates JsonLoader; symptoms are fallbacks silently not working. Verify in a staging smoke test that a deliberately missing key resolves.
• Config drift — fallback locale changed or removed during a config refactor; covered by a single assertion test.

Ramp-up

• Engineering: under a day to understand and integrate; the package's surface is small enough to read end-to-end, which is unusual and reduces onboarding drag.
• Product/design: minimal — one concept to internalize (missing key → source-locale string rather than blank/broken UI), plus the requirement that JSON keys stay in sync with design specs.
• Localization/content team: the meaningful ramp-up. They need to read fallback-hit telemetry and prioritize translation work by impact. Budget a short working session to define which keys are "never acceptable to fall back" (legal, compliance, checkout) versus "graceful degradation acceptable."
• TPM recommendation: adopt for a pilot with an explicit two-sprint exit criterion — measured fallback rate on the pilot surface plus a validated CI check — and a pre-agreed decision point on fork-versus-accept for the single-maintainer risk.