PHPackages gboquizosanchez/icu-i18n - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Localization & i18n](/categories/localization) 4. / 5. gboquizosanchez/icu-i18n ActiveLibrary[Localization & i18n](/categories/localization) gboquizosanchez/icu-i18n ======================== Advanced ICU Translation support for Laravel with regional fallback strategies. 2.0.1(2mo ago)05MITPHPPHP ^8.3 Since Nov 22Pushed 2mo agoCompare [ Source](https://github.com/gboquizosanchez/icu-i18n)[ Packagist](https://packagist.org/packages/gboquizosanchez/icu-i18n)[ Docs](https://github.com/gboquizosanchez/icu-i18n)[ RSS](/packages/gboquizosanchez-icu-i18n/feed)WikiDiscussions 1.x Synced today READMEChangelog (2)Dependencies (30)Versions (4)Used By (0) [![i18n](https://raw.githubusercontent.com/twitter/twemoji/master/assets/svg/1f310.svg)](https://raw.githubusercontent.com/twitter/twemoji/master/assets/svg/1f310.svg)`gboquizosanchez/icu-i18n` ========================== [](#gboquizosanchezicu-i18n) **Advanced ICU Internationalization for Laravel** [![Latest Stable Version](https://camo.githubusercontent.com/8c25998b1ba7bf178ecaeb2e86978fe0c4e428e1d2d5946dcd212dcb1cdf750f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67626f7175697a6f73616e6368657a2f6963752d6931386e2e737667)](https://packagist.org/packages/gboquizosanchez/icu-i18n)[![Total Downloads](https://camo.githubusercontent.com/16a52b8e8b417bc49bf2b738f3eb934d9b17d4ea0c36534a13ce40ffc5aa5017/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f67626f7175697a6f73616e6368657a2f6963752d6931386e2e737667)](https://packagist.org/packages/gboquizosanchez/icu-i18n)[![PHP](https://camo.githubusercontent.com/31a87e1f22b529af58a2615dde6bcd4902061209db5e98adc4b5dff3e99f5f02/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253545382e332d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://packagist.org/packages/gboquizosanchez/icu-i18n)[![Laravel](https://camo.githubusercontent.com/ef749269b4e188533479a48e8d4c00604c54f02116015dee66908c8d8e80cf43/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d4646324432303f6c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)](https://packagist.org/packages/gboquizosanchez/icu-i18n)[![License: MIT](https://camo.githubusercontent.com/6fd529fdc57adf8eb89582bee619d571fd9037b380418c50bb57e9c91598e03b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d3232433535452e737667)](LICENSE.md)[![PHPStan](https://camo.githubusercontent.com/71c551554fecfe5d1b44cbe091fcf072f297bc7fa2e5f910da8272eb0e7086e3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c2532304d61782d626c7565)](https://phpstan.org/)[![Tests](https://camo.githubusercontent.com/600447d23e0f73abc4988a83007993cf06dbbac7db0af553fd0a9c63d65a0b8f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54657374732d5065737425323076342d394332374230)](https://pestphp.com/) --- *Your app uses `es_MX` but vendor packages only ship `es`? Fixed.**Complex plurals for Russian, Arabic, Polish and Swahili with zero extra configuration.* --- Why this package? ----------------- [](#why-this-package) Laravel's built-in translation support works great for simple cases — but falls short in real-world multilingual apps: ProblemWithout this packageWith `icu-i18n`Plurals in Russian / Arabic / Polish❌ Impossible with `:count`✅ Native ICU MessageFormatApp in `es_MX`, vendor only has `es`❌ Missing keys or wrong locale✅ Automatic regional fallbackCurrency formatting by locale❌ Manual formatting✅ `{amount, number, currency}`Localized dates❌ Carbon + extra setup✅ `{date, date, long}`Drop-in replacement—✅ Same `__()`, `trans()`, `@lang`--- 🚀 Features ---------- [](#-features) - **ICU MessageFormat Support**: Use standard syntax like `{count, plural, ...}` or `{gender, select, ...}` directly in your translation files. - **Smart Regional Fallback**: Automatically degrades specific namespaces or files from a regional locale (e.g., `es_MX`) to a base locale (e.g., `es`). - *Problem Solved:* You want your app to use `es_MX` for currency formatting, but your vendor packages (like `laravel/ui` or `spatie/permission`) only publish translations in `es`. This package handles that automatically. - **Seamless Integration**: Works as a drop-in replacement for `trans()`, `__()`, and `@lang`. - **Native Performance**: Uses PHP's native `intl` extension and `MessageFormatter`. --- 📦 Installation -------------- [](#-installation) ``` composer require gboquizosanchez/icu-i18n ``` Publish the configuration file: ``` php artisan vendor:publish --provider="Boquizo\IcuI18n\I18nServiceProvider" ``` **Requirements:** PHP ^8.3 · ext-intl · Laravel 12 or 13 --- 🔧 Configuration --------------- [](#-configuration) The configuration file `config/icu.php` controls the **Regional Fallback Strategy**. ### How it works [](#how-it-works) When you request a translation (e.g., `__('validation.required')`) while your app locale is set to **Regional** (e.g., `es_MX`), the translator decides whether to use `es_MX` or fall back to `es` based on two rules: 1. **Namespace Allowlist**: If the translation namespace is **NOT** in the `namespaces` list, it falls back to the base language (`es`). 2. **File Blocklist**: If the translation file is in the `files` list, it forces the base language (`es`), even if the namespace is allowlisted. ### Default Configuration [](#default-configuration) ``` // config/icu.php return [ 'regionals' => [ /* * Allowlisted Namespaces. * These will use the full regional locale (e.g. es_MX). * '*' represents your application's local files (lang/es_MX/...). * Vendor packages are excluded by default to prevent missing translation errors. */ 'namespaces' => [ '*', ], /* * Blocklisted Files. * These will ALWAYS force the base locale (e.g. es). * Useful for standard Laravel files that usually come in generic locale folders. */ 'files' => [ // 'validation', // 'auth', // 'passwords', ], ], ]; ``` --- 📖 Usage ------- [](#-usage) ### 1. ICU MessageFormat [](#1-icu-messageformat) Use standard ICU syntax in your JSON or PHP translation files. **`lang/en/messages.php`** ``` return [ 'welcome' => 'Hello, {name}.', 'balance' => 'Your balance is {amount, number, currency}', 'apples' => '{count, plural, =0{No apples} one{One apple} other{# apples}}', 'gender' => '{gender, select, male{Welcome, sir} female{Welcome, ma\'am} other{Welcome}}', 'audit' => '{user} performed an action on {date, date, long}', ]; ``` **In your Blade views:** ``` {{-- Basic variable --}} {{ __('messages.welcome', ['name' => 'John']) }} {{-- Output: Hello, John. --}} {{-- Automatic currency formatting (uses app locale) --}} {{ __('messages.balance', ['amount' => 1250.50]) }} {{-- Output (en_US): Your balance is $1,250.50 --}} {{-- Output (es_ES): Tu saldo es 1.250,50 € --}} {{-- Complex pluralization --}} {{ __('messages.apples', ['count' => 1]) }} {{-- One apple --}} {{ __('messages.apples', ['count' => 5]) }} {{-- 5 apples --}} {{ __('messages.apples', ['count' => 0]) }} {{-- No apples --}} {{-- Gender / select --}} {{ __('messages.gender', ['gender' => 'female']) }} {{-- Output: Welcome, ma'am --}} ``` ### 2. Advanced pluralization per language [](#2-advanced-pluralization-per-language) ICU supports the pluralization rules of **every language** following the CLDR standard: **Russian** — 3 plural forms ``` // lang/ru/messages.php 'items' => 'Dimitri купил {count, plural, one{# товар} few{# товара} other{# товаров}}.', ``` ``` count=1 → Dimitri купил 1 товар. count=2 → Dimitri купил 2 товара. count=5 → Dimitri купил 5 товаров. count=105 → Dimitri купил 105 товаров. ``` **Arabic** — 6 forms + dual ``` // lang/ar/messages.php 'products' => '{count, plural, =1{منتج واحد} =2{منتجان} few{# منتجات} many{# منتجاً} other{# منتج}}', ``` **Polish** — 4 plural forms ``` // lang/pl/messages.php 'products' => '{count, plural, one{# produkt} few{# produkty} many{# produktów} other{# produktu}}', ``` **Slovenian** — 4 forms including dual ``` // lang/sl/messages.php 'items' => '{count, plural, one{# izdelek} two{# izdelka} few{# izdelki} other{# izdelkov}}', ``` ### 3. Handling Object Parameters [](#3-handling-object-parameters) The translator automatically converts `DateTime` objects to timestamps and objects implementing `__toString()` to strings before passing them to the ICU formatter: ``` $user = new User(['name' => 'Alice']); // implements __toString $date = new DateTime('2023-10-01'); echo __('messages.audit', ['user' => $user, 'date' => $date]); // Output (en_US): Alice performed an action on October 1, 2023 // Output (es_ES): Alice realizó una acción el 1 de octubre de 2023 // Output (ar_SA): أجرت Alice إجراءً في ١ أكتوبر ٢٠٢٣ ``` --- 🧩 Regional Fallback Examples ---------------------------- [](#-regional-fallback-examples) Assume `App::setLocale('es_MX')`. #### Scenario A: Application Strings [](#scenario-a-application-strings) You have a file `lang/es_MX/home.php`. - **Config**: `namespaces => ['*']` - **Call**: `__('home.title')` - **Result**: Loads from `es_MX`. (Matches `*` allowlist ✅) #### Scenario B: Vendor Package [](#scenario-b-vendor-package) You use a package `courier` that only has translations in `lang/vendor/courier/es/messages.php`. - **Config**: `namespaces => ['*']` (does NOT include `courier`) - **Call**: `__('courier::messages.error')` - **Result**: Loads from `es`. (Namespace `courier` not allowlisted → degrades to base locale ✅) #### Scenario C: Validation Files [](#scenario-c-validation-files) You want to use standard Laravel validation messages which typically exist in `lang/es/validation.php`, not `es_MX`. - **Config**: `files => ['validation']` - **Call**: `__('validation.required')` - **Result**: Loads from `es`. (File `validation` is blocklisted → forces base locale ✅) --- ICU Syntax Reference -------------------- [](#icu-syntax-reference) TypeSyntaxExampleVariable`{variable}``{name}`Number`{var, number}``{count, number}`Currency`{var, number, currency}``{amount, number, currency}`Short date`{var, date, short}``{date, date, short}`Long date`{var, date, long}``{date, date, long}`Plural`{var, plural, one{} other{}}`See examples aboveSelect`{var, select, val1{} other{}}``{gender, select, male{} female{} other{}}``#` in pluralReplaced by the count value`{count, plural, other{# items}}`--- 🧪 Testing --------- [](#-testing) ``` composer test ``` This package uses [Pest v4](https://pestphp.com/) with architecture and Laravel plugins. Static analysis runs via [Larastan](https://github.com/larastan/larastan) at the maximum level. ### Troubleshooting [](#troubleshooting) If you encounter issues: 1. **Check the logs** — Laravel logs may contain helpful error messages. 2. **Verify requirements** — Ensure PHP and Laravel versions meet the minimum requirements. 3. **Clear cache** — Run `php artisan config:clear` and `php artisan cache:clear`. 4. **Open an issue** — [Report bugs or request features](https://github.com/gboquizosanchez/icu-i18n/issues/new). --- Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to: - 🐛 **Report bugs** via [GitHub Issues](https://github.com/gboquizosanchez/icu-i18n/issues/new) - 💡 **Suggest features** or improvements - 🔧 **Submit pull requests** with bug fixes or enhancements - 📖 **Improve documentation** or add language examples Please make sure all tests pass and the code follows the style enforced by [Laravel Pint](https://laravel.com/docs/pint) before submitting a PR. --- Credits ------- [](#credits) - **Author**: [Germán Boquizo Sánchez](mailto:germanboquizosanchez@gmail.com) - **Framework**: [Laravel](https://laravel.com/) - **Standard**: [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) - **Pluralization rules**: [CLDR Plural Rules](https://cldr.unicode.org/index/cldr-spec/plural-rules) - **Contributors**: [View all contributors](../../contributors) --- 📄 License --------- [](#-license) This package is open-source software licensed under the [MIT License](LICENSE.md). --- Made with ❤️ for the PHP · Laravel · i18n community ### Health Score 38 — LowBetter than 83% of packages Maintenance83 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity52 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~46 days Total 4 Last Release 88d ago Major Versions 1.0.0 → 2.0.02026-04-08 1.x-dev → 2.0.12026-04-08 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/20032391?v=4)[Germán Boquizo Sánchez](/maintainers/gboquizosanchez)[@gboquizosanchez](https://github.com/gboquizosanchez) --- Top Contributors [![gboquizosanchez](https://avatars.githubusercontent.com/u/20032391?v=4)](https://github.com/gboquizosanchez "gboquizosanchez (7 commits)") --- Tags fallbacki18nicuinternationalizationintllaravellocalizationmessageformatregionaltranslationlaraveli18nicutranslation ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/gboquizosanchez-icu-i18n/health.svg) ``` [![Health](https://phpackages.com/badges/gboquizosanchez-icu-i18n/health.svg)](https://phpackages.com/packages/gboquizosanchez-icu-i18n) ``` ### Alternatives [defstudio/telegraph A laravel facade to interact with Telegram Bots 816334.1k3](/packages/defstudio-telegraph)[bezhansalleh/filament-language-switch Zero config Language Switch(Changer/Localizer) plugin for filamentphp admin 3581.3M28](/packages/bezhansalleh-filament-language-switch)[kkomelin/laravel-translatable-string-exporter Translatable String Exporter for Laravel 3301.5M20](/packages/kkomelin-laravel-translatable-string-exporter)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 44855.7k](/packages/harris21-laravel-fuse)[erag/laravel-lang-sync-inertia A powerful Laravel package for syncing and managing language translations across backend and Inertia.js (Vue/React/Svelte) frontends, offering effortless localization, auto-sync features, and smooth multi-language support for modern Laravel applications. 4925.3k](/packages/erag-laravel-lang-sync-inertia)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5022.0k](/packages/simplestats-io-laravel-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)