Weave Code
Json Fallback Hotfix Laravel Package
laravel-lang/json-fallback-hotfix
Restore expected JSON translation fallback behavior in Laravel with this Laravel Lang hotfix. It ensures missing JSON keys resolve through your configured fallback locale instead of returning raw keys, helping multilingual apps stay consistent. Drop-in Composer package for affected Laravel versions.
Adds support for fallback JSON string translation
Frequently asked questions about Json Fallback Hotfix
- How do I install laravel-lang/json-fallback-hotfix in a Laravel app?
- Install it with Composer using composer require laravel-lang/json-fallback-hotfix. There is no configuration file to publish, no database table and no application code to rewrite, so the package simply takes effect once it is autoloaded. Existing lang/*.json files keep working as before. You only need to make sure config/app.php (or your app config) defines the fallback_locale you expect.
- Which Laravel and PHP versions does laravel-lang/json-fallback-hotfix support?
- Release 2.3.0 adds Laravel 13 support, and the changelog lists that bump as source changes only, which typically means widened composer.json constraints and an extended CI matrix rather than new runtime logic. Because the package patches framework internals, you should read the actual laravel/framework and php constraints in its composer.json rather than assume the README covers your version. Test the exact Laravel and PHP combination you run in production, at both your minimum and maximum dependency versions.
- Why does a missing JSON translation key return the raw key instead of the fallback locale?
- In affected Laravel versions, JSON string lookups that miss in the active locale can return the key itself instead of resolving through the configured fallback_locale. That is why a non-English UI suddenly shows English source strings or raw keys such as Login instead of the translated equivalent. This package patches the translator behavior so missing JSON keys fall through to the fallback language. It is a targeted hotfix, not a general change to how translations are loaded.
- Does it conflict with other laravel-lang translation packages or with PHP array lang files?
- The package is designed to work alongside laravel-lang translation packages, since it only adjusts the missing-key fallback path rather than replacing how translation files are discovered. Projects that exclusively use PHP array lang files, or that serve translations from a database or CMS, get little or no benefit because the defect it addresses is specific to JSON translation files. If you run several localization packages, confirm the override order is deterministic in your own application.
- Does the hotfix change Lang::has, replacement parameters, trans_choice, or nested and namespaced keys?
- The stated scope is restoring fallback resolution for missing JSON keys, but you should not infer the full behavior surface from the README. Verify how Lang::get and the __() helper behave with replacement parameters, whether Lang::has reports the fallback value as present, and how trans_choice pluralization resolves when only the fallback locale has the key. Namespaced and nested keys deserve their own checks against your real key inventory. Add regression tests for each of these paths before rolling out.
- Is it compatible with Laravel Octane, Swoole and long-running workers?
- Because the package works by patching the translator, the resolved translator instance is created once per worker and cached for the worker lifetime. In an Octane or Swoole setup that means the patched behavior should persist between requests, but it also means you must confirm the binding is applied before workers boot. Run a smoke test under Octane with two locales and a missing key, and confirm the fallback still resolves after a worker restart and a config reload.
- What exactly does the package override, and is the override order deterministic?
- Architecturally it is a narrow behavioral shim that sits adjacent to Illuminate\Translation\Translator and corrects JSON string lookups, with no schema, config contract or events of its own. Whether that is implemented as a container binding, a translator subclass or something else determines how it interacts with other localization packages, so confirm it from the source. If you rely on multiple packages that touch the translator, verify the resolution order in your own bootstrapping rather than assuming it.
- Is laravel-lang/json-fallback-hotfix safe for production and actively maintained?
- It is MIT licensed and installable, but it is a single-maintainer package within the laravel-lang ecosystem with a small star count, so there is no SLA, security-response commitment or deprecation policy you can plan against. Treat it as a defect-workaround dependency: track it with a named owner and an exit condition rather than absorbing it silently into your baseline. Note that failures are quiet rather than loud, since the symptom is raw keys appearing in a non-English interface, so add a regression test or monitoring around translated output.
- What alternatives are there if I do not want a dependency on Laravel framework internals?
- The usual workarounds are a custom translator subclass, a __() wrapper that retries against the fallback locale manually, or duplicating every key into each lang/*.json file. All three cost real engineering or maintenance time, which is exactly the cost this package removes. A fourth option is waiting for an upstream Laravel fix, and you should watch for that because once it lands the package becomes dead weight still pinned in composer.json. PHP array lang files avoid the problem entirely if you can switch.
- How should I test JSON translation fallback after installing the hotfix?
- Write a regression test that sets an active locale and a different fallback_locale, then asserts that a key present only in the fallback file resolves to the fallback string instead of the raw key. Cover per-key fallback through both Lang::get and __(), plus replacement parameters, Lang::has, and trans_choice where you use plurals. Run the suite in CI at your minimum and maximum supported Laravel versions, since a green build alone is not proof that a framework patch still behaves correctly after an upgrade.
Weaver
How can I help you explore Laravel packages today?