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. 1.0.0(5mo ago)02MITPHPPHP ^8.3 Since Nov 22Pushed 5mo agoCompare [ Source](https://github.com/gboquizosanchez/icu-i18n)[ Packagist](https://packagist.org/packages/gboquizosanchez/icu-i18n)[ Docs](https://github.com/gboquizosanchez/icu-translation)[ RSS](/packages/gboquizosanchez-icu-i18n/feed)WikiDiscussions 1.x Synced 1mo ago READMEChangelog (1)Dependencies (15)Versions (2)Used By (0) Laravel ICU Translation ======================= [](#laravel-icu-translation) [![Latest Stable Version](https://camo.githubusercontent.com/8c25998b1ba7bf178ecaeb2e86978fe0c4e428e1d2d5946dcd212dcb1cdf750f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67626f7175697a6f73616e6368657a2f6963752d6931386e2e737667)](https://packagist.org/packages/gboquizosanchez/icu-i18n)[![Software License](https://camo.githubusercontent.com/4141875b9db06b6e19ee4c8c4f14f34b47dabb4fcdad7816e338a79666b0aacb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d7265642e737667)](https://packagist.org/packages/gboquizosanchez/icu-i18n)[![Total Downloads](https://camo.githubusercontent.com/16a52b8e8b417bc49bf2b738f3eb934d9b17d4ea0c36534a13ce40ffc5aa5017/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f67626f7175697a6f73616e6368657a2f6963752d6931386e2e737667)](https://packagist.org/packages/gboquizosanchez/icu-i18n) **Advanced Internationalization support for Laravel.** This package extends the native Laravel Translator to provide support for **ICU MessageFormat** (complex plurals, gender selection, localized currency/dates) and implements a smart **Regional Locale Fallback** strategy to handle vendor packages gracefully. πŸš€ 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) You can install the package via composer: ``` composer require vendor/icu-translation ``` Publish the configuration file: ``` php artisan vendor:publish --provider="Vendor\IcuTranslation\I18nServiceProvider" ``` πŸ”§ Configuration --------------- [](#-configuration) The configuration file `config/icu.php` controls the **Regional Fallback Strategy**. ### How logic works [](#how-logic-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 Allowed list**: 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 allowed listed. ### Default Configuration [](#default-configuration) ``` // config/icu.php return [ 'regionals' => [ /* * Allowed list Namespaces. * These will use the full regional locale (es_MX). * '*' represents your application's local files (lang/es_MX/...). * Vendor packages are excluded by default to prevent missing translation errors. */ 'namespaces' => [ '*', ], /* * Excluded Files. * These will ALWAYS force the base locale (es). * Useful for standard Laravel files that usually come in generic folders. */ 'files' => [ // 'validation', // 'auth', // 'passwords', ], ], ]; ``` πŸ“– Usage ------- [](#-usage) ### 1. ICU MessageFormat [](#1-icu-messageformat) You can 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}}', ]; ``` **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 --}} {{-- Complex Pluralization --}} {{ __('messages.apples', ['count' => 5]) }} {{-- Output: 5 apples --}} ``` ### 2. Handling Object Parameters [](#2-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]); ``` 🧩 Regional Fallback Examples ---------------------------- [](#-regional-fallback-examples) Assume `App::setLocale('es_MX')`. #### Scenario A: Application Strings [](#scenario-a-application-strings) You have a file `lang/en_GB/home.php`. - **Config**: `namespaces => ['*']` - **Call**: `__('home.title')` - **Result**: Loads from `en_GB`. (Matches `*` allowed list). #### 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 `en`. (Namespace 'courier' is not allowed listed -> 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/en/validation.php`, not `en_US`. - **Config**: `files => ['validation']` - **Call**: `__('validation.required')` - **Result**: Loads from `en`. (File 'validation' is blocklisted -> forces base locale). πŸ§ͺ Testing --------- [](#-testing) ``` composer test ``` ### Getting Help [](#getting-help) If you encounter issues: 1. **Check the logs** - Laravel logs may contain helpful error messages 2. **Verify requirements** - Ensure PHP and Laravel versions meet 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/phpstan-report/issues/new) Contributing ------------ [](#contributing) We welcome contributions! Please feel free to: - πŸ› **Report bugs** through GitHub issues - πŸ’‘ **Suggest features** or improvements - πŸ”§ **Submit pull requests** with bug fixes or enhancements - πŸ“– **Improve documentation** or add examples Credits πŸ§‘β€πŸ’» ----------- [](#credits-‍) - **Author**: [GermΓ‘n Boquizo SΓ‘nchez](mailto:germanboquizosanchez@gmail.com) - **Built with**: [PHPStan](https://phpstan.org/) - The powerful PHP static analysis tool - **Framework**: [Laravel](https://laravel.com/) - The PHP framework - **Contributors**: [View all contributors](../../contributors) πŸ“„ License --------- [](#-license) This package is open-source software licensed under the [MIT License](LICENSE.md). πŸ“¦ Dependencies -------------- [](#-dependencies) ### PHP dependencies πŸ“¦ [](#php-dependencies-) - Spatie Laravel Package Tools [![Latest Stable Version](https://camo.githubusercontent.com/a084a7cd84af5b26d933c04e01fc7d1d7d176ddf37920260d0f4c600ba2133a6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d312e39322e372d626c7565)](https://packagist.org/packages/spatie/laravel-package-tools) #### Develop dependencies πŸ”§ [](#develop-dependencies-) - Hermes Dependencies [![Latest Stable Version](https://camo.githubusercontent.com/a27bb88c89f9c450da561b4073e694a280af914046264e7a83dff5dab8142af9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d312e322e302d626c7565)](https://packagist.org/packages/hermes/dependencies) - Larastan Larastan [![Latest Stable Version](https://camo.githubusercontent.com/64fa7cedce191ca73aa90eccb4f53c14cc1dc174f4ecb08e2f5b3f8ffaa829b2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d76332e382e302d626c7565)](https://packagist.org/packages/larastan/larastan) - Laravel Pint [![Latest Stable Version](https://camo.githubusercontent.com/e7399b8166ad18583736c6ac09811fb3c760d0677a4184bfa5a581ea64accfb8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d76312e32352e312d626c7565)](https://packagist.org/packages/laravel/pint) - Nunomaduro Collision [![Latest Stable Version](https://camo.githubusercontent.com/ca7d2cf4d7f6fd6d9e63505b273f113827c69f8f76367635caa92d989984ee54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d76382e382e332d626c7565)](https://packagist.org/packages/nunomaduro/collision) - Orchestra Testbench [![Latest Stable Version](https://camo.githubusercontent.com/4a2a4138acce97f3162a0bb4bc701e6cd7fdbc8fa6c7efdf05d296d35b4b584d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d7631302e372e302d626c7565)](https://packagist.org/packages/orchestra/testbench) - Pestphp Pest [![Latest Stable Version](https://camo.githubusercontent.com/2270acb70739343da32cd3db801cc69fe40372a52984384826101a177b68f437/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d76342e312e342d626c7565)](https://packagist.org/packages/pestphp/pest) - Pestphp Pest Plugin Arch [![Latest Stable Version](https://camo.githubusercontent.com/e3ae2e10e399b8ac25a1ddb24a1776ebeda955d1fe4e89f8a21b2898bd5d7f58/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d76342e302e302d626c7565)](https://packagist.org/packages/pestphp/pest-plugin-arch) - Pestphp Pest Plugin Laravel [![Latest Stable Version](https://camo.githubusercontent.com/e3ae2e10e399b8ac25a1ddb24a1776ebeda955d1fe4e89f8a21b2898bd5d7f58/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d76342e302e302d626c7565)](https://packagist.org/packages/pestphp/pest-plugin-laravel) - Phpstan Extension Installer [![Latest Stable Version](https://camo.githubusercontent.com/4c03ed27cd1f1e585e2af7ccd4ec026f17e39a6d7d8470707a50165bfeac066c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d312e342e332d626c7565)](https://packagist.org/packages/phpstan/extension-installer) - Phpstan Phpstan Deprecation Rules [![Latest Stable Version](https://camo.githubusercontent.com/1456e3d0c430d24ca38c95e387bc55049a4782b6ad409d3703169c269e650914/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d322e302e332d626c7565)](https://packagist.org/packages/phpstan/phpstan-deprecation-rules) - Phpstan Phpstan Phpunit [![Latest Stable Version](https://camo.githubusercontent.com/bb2951cbeb92304c65d8950465f519d278f4701ce3580251f6ab9accd5de3b86/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d322e302e382d626c7565)](https://packagist.org/packages/phpstan/phpstan-phpunit) - Spatie Laravel Ray [![Latest Stable Version](https://camo.githubusercontent.com/bc1c25ab2ab7650a8b14b84afaffcfbd71e14ab28f27453f364c114109c3ce36/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f737461626c652d312e34322e302d626c7565)](https://packagist.org/packages/spatie/laravel-ray) **Made with ❀️ for the PHP community** ### Health Score 34 β€” LowBetter than 77% of packages Maintenance70 Regular maintenance activity Popularity2 Limited adoption so far Community6 Small or concentrated contributor base Maturity50 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 ~0 days Total 2 Last Release 172d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/0e360fba0cbca71392811fad1046d47397298adf9a191090e62eeeeab864e21d?d=identicon)[gboquizosanchez](/maintainers/gboquizosanchez) --- Top Contributors [![gboquizosanchez](https://avatars.githubusercontent.com/u/20032391?v=4)](https://github.com/gboquizosanchez "gboquizosanchez (1 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 [kkomelin/laravel-translatable-string-exporter Translatable String Exporter for Laravel 3291.4M10](/packages/kkomelin-laravel-translatable-string-exporter)[smousss/laravel-globalize Make Laravel projects translatable in a matter of seconds! 2266.3k](/packages/smousss-laravel-globalize) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)