Download the PHP package i18nagent/laravel-locale-chain without Composer

i18n-laravel-locale-chain

Smart locale fallback chains for Laravel -- because pt-BR users deserve pt-PT translations, not English.

The Problem

Laravel's translation system has two limitations:

1. Single fallback locale. The fallback_locale config only supports one language. There is no intermediate fallback. If a user requests pt-BR and you only have pt-PT translations, Laravel skips pt-PT entirely and shows English (or whatever your fallback_locale is).

2. JSON translation files ignore fallback entirely. This is a known Laravel bug. When you use JSON translation files (lang/pt-BR.json), Laravel does not check the fallback locale's JSON file. PHP files (lang/pt-BR/messages.php) respect fallback_locale, but JSON files do not.

Example: A user's browser sends Accept-Language: pt-BR. Your Laravel app has pt-PT translations but no pt-BR locale. Laravel skips pt-PT entirely and shows English.

The same thing happens with es-MX -> es, fr-CA -> fr, de-AT -> de, and every other regional variant.

Your users see English when a perfectly good translation exists in a sibling locale.

The Solution

One service provider. Zero code changes. Laravel auto-discovery handles everything.

i18n-laravel-locale-chain replaces Laravel's TranslationServiceProvider with a ChainTranslator that walks a configurable fallback chain for both PHP and JSON translation files. Missing keys in the primary locale are resolved from fallback locales before reaching the app's default language. Your existing translation calls just work:

• __('key') helper
• trans('key') helper
• @lang('key') Blade directive
• {{ __('key') }} in Blade templates
• All Illuminate\Translation functions

Installation

That's it. Laravel auto-discovers the service provider. All 75 default fallback chains are active immediately.

Quick Start

1. Install (auto-discovery does the rest)

No configuration needed. A pt-BR user will now see pt-PT translations when pt-BR is not available, and JSON translation files will correctly fall back through the chain.

2. (Optional) Publish the config file

This creates config/locale-chain.php where you can customize chains or disable the package.

3. (Optional) Add custom chains

Your custom chains are merged with the 75 built-in defaults. Keys you specify replace the corresponding default chain.

Configuration Modes

Default (zero config)

Just install the package. Uses all 75 built-in fallback chains covering Chinese, Portuguese, Spanish, French, German, Italian, Dutch, English, Arabic, Norwegian, and Malay regional variants.

Config file

Programmatic

Priority order (highest to lowest):

1. setChains() call (programmatic API)
2. config/locale-chain.php config file
3. Built-in defaults (zero-config)

API Reference

FallbackMap::defaults()

Returns the 75 built-in fallback chains as array<string, list<string>>.

FallbackMap::merge(?array $overrides = null, bool $mergeDefaults = true)

Merge overrides on top of the default chains. Returns a new array -- the defaults are never mutated.

ChainTranslator

Extends Illuminate\Translation\Translator. Overrides get() to walk a configurable fallback chain for both PHP and JSON files.

LocaleChainServiceProvider

Extends TranslationServiceProvider. Replaces the translator singleton with ChainTranslator. Auto-discovered by Laravel.

Config Reference

Default Fallback Map

Chinese (Traditional)

Chinese (Simplified)

Portuguese

Spanish

French

German

Italian

Dutch

English

Arabic

Norwegian

Malay

How It Works

1. Laravel auto-discovers LocaleChainServiceProvider, which extends Laravel's TranslationServiceProvider.
2. The service provider replaces the translator singleton with ChainTranslator, which extends Illuminate\Translation\Translator.
3. ChainTranslator overrides the get() method to walk a configurable fallback chain.
4. For each key lookup, it tries the primary locale first, then each locale in the chain, then the configured fallback_locale.
5. Crucially, it checks JSON translation files at each step -- fixing Laravel's bug where JSON files ignore fallback entirely.
6. The original terminal fallback (your fallback_locale) is preserved at the end of the chain.
7. Your existing __(), trans(), and @lang() calls work without any changes.

Example

A working example route is included in the example/ directory. Copy it to your routes/web.php:

Then test:

See example/README.md for full details.

FAQ

Is this production-ready? Yes. The library extends Laravel's Translator class using its public API. No monkey-patching, no private API access.

Performance impact? Negligible. Translation files are loaded once per locale per request via Laravel's built-in FileLoader caching. The chain walking adds only a few array lookups per missing key.

Does it fix the JSON fallback bug? Yes. This is one of the two main features. Laravel's stock translator does not check JSON fallback files -- ChainTranslator checks JSON files at every step of the fallback chain.

Can I use a non-English default locale? Yes. The fallback chains are independent of your app's locale and fallback_locale. They only control which sibling locales are checked before the default language.

Can I disable it? Yes. Set 'enabled' => false in config/locale-chain.php, or remove the package entirely.

Does it work with Laravel Livewire / Inertia.js? Yes. Both use Laravel's translation system under the hood, so fallback chains work automatically.

Does it work with API resources? Yes. Any code that uses __(), trans(), or the Translator service will benefit from fallback chains.

Minimum Laravel version? Laravel 10 (LTS). Also supports Laravel 11 and Laravel 12.

Contributing

• Open issues for bugs or feature requests.
• PRs welcome, especially for adding new locale fallback chains.
• Run tests with: ./vendor/bin/phpunit

License

MIT License - see LICENSE file.

Built by i18nagent.ai