Weave Code
Json Fallback Laravel Package
laravel-lang/json-fallback
Adds a JSON fallback translator to Laravel so missing JSON translation keys resolve to your fallback locale instead of showing raw keys. Drop-in service provider, no config required.
Adds support for fallback JSON string translation
Frequently asked questions about Json Fallback
- How do I install and configure laravel-lang/json-fallback in my Laravel project?
- Run `composer require laravel-lang/json-fallback`, then register the service provider in `config/app.php` under the `providers` array. No additional configuration is needed unless you want to customize the fallback locale, which you can set in `config/app.php` under `fallback_locale`. The package replaces Laravel’s default JsonLoader automatically.
- Does this package support Laravel 10, 11, 12, or 13? What about PHP versions?
- This package is actively maintained for Laravel 10 through 13 and requires PHP 8.1 or higher. Check the [GitHub repository](https://github.com/Laravel-Lang/json-fallback) or Packagist for the latest compatibility details before installing.
- Will this break my existing JSON translation files (e.g., resources/lang/*.json)?
- No, this package is backward-compatible. Your existing JSON files will continue to work as long as they use flat key-value pairs (e.g., `"auth.login": "Connexion"`). If you use nested JSON (e.g., `"auth": { "login": "Connexion" }`), you’ll need to pre-process the keys to flatten them (e.g., `auth.login`).
- Can I use multiple fallback locales (e.g., fr-CA → fr-FR → en)?
- Currently, this package supports a single fallback locale (e.g., `fr` falls back to `en`). For multi-level fallbacks, you’ll need to extend the package or create a wrapper service that implements hierarchical fallback logic. The default behavior is configurable via `config/app.php`.
- How does this package handle malformed JSON files or missing keys?
- The package assumes well-formed JSON files. If a JSON file is malformed, it will throw an error. To prevent this, validate your JSON files using tools like `jsonlint` in your CI/CD pipeline. Missing keys will trigger the fallback mechanism if configured, but ensure your fallback locale has the required translations.
- Does this work with Laravel Mix or Vite for frontend JSON assets?
- Yes, this package integrates seamlessly with Laravel Mix and Vite. Since it replaces Laravel’s JsonLoader, your frontend assets (e.g., Vue/React bundles) can still rely on the same translation keys. Just ensure your JSON files are consistent between backend and frontend.
- What if my JSON translations use nested structures (e.g., `"auth": { "login": "Connexion" }`)?
- This package is optimized for flat key-value pairs (e.g., `auth.login`). If your JSON uses nested structures, you’ll need to pre-process the keys to flatten them (e.g., `auth.login` instead of `auth.login`). Alternatively, you can extend the package to support nested JSON.
- Is there a performance impact when using fallback translations?
- The performance impact is negligible—benchmarks show around 1ms per fallback lookup. This is ideal for high-traffic APIs or applications where translations are dynamically loaded. The package is designed to be lightweight and efficient.
- Can I dynamically set the fallback locale per request (e.g., based on user preferences)?
- The fallback locale is currently set globally in `config/app.php`. To dynamically override it per request, you’ll need to extend the package or use middleware to temporarily modify the `App::setLocale()` behavior before translation calls.
- Are there alternatives to this package for JSON translation fallbacks?
- If you need multi-level fallbacks or nested JSON support, consider extending this package or using a custom solution. For simpler needs, Laravel’s native `trans()` with array-based fallbacks (in `resources/lang/*.php`) might suffice, but this package is specifically designed for JSON-based workflows, especially in decoupled architectures (e.g., Laravel backend + JS frontend).
Weaver
How can I help you explore Laravel packages today?