Download the PHP package gboquizosanchez/icu-i18n without Composer

# `gboquizosanchez/icu-i18n` **Advanced ICU Internationalization for Laravel** [](https://packagist.org/packages/gboquizosanchez/icu-i18n) [](https://packagist.org/packages/gboquizosanchez/icu-i18n) [](https://packagist.org/packages/gboquizosanchez/icu-i18n) [](https://packagist.org/packages/gboquizosanchez/icu-i18n) [](LICENSE.md) [](https://phpstan.org/) [](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?

Laravel's built-in translation support works great for simple cases — but falls short in real-world multilingual apps:

🚀 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

Publish the configuration file:

Requirements: PHP ^8.3 · ext-intl · Laravel 12 or 13

🔧 Configuration

The configuration file config/icu.php controls the Regional Fallback Strategy.

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

📖 Usage

1. ICU MessageFormat

Use standard ICU syntax in your JSON or PHP translation files.

lang/en/messages.php

In your Blade views:

2. Advanced pluralization per language

ICU supports the pluralization rules of every language following the CLDR standard:

Russian — 3 plural forms

Arabic — 6 forms + dual

Polish — 4 plural forms

Slovenian — 4 forms including dual

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:

🧩 Regional Fallback Examples

Assume App::setLocale('es_MX').

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

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

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

🧪 Testing

This package uses Pest v4 with architecture and Laravel plugins. Static analysis runs via Larastan at the maximum level.

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.

Contributing

Contributions are welcome! Please feel free to:

• 🐛 Report bugs via GitHub Issues
• 💡 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 before submitting a PR.

Credits

• Author: Germán Boquizo Sánchez
• Framework: Laravel
• Standard: ICU MessageFormat
• Pluralization rules: CLDR Plural Rules
• Contributors: View all contributors

📄 License

This package is open-source software licensed under the MIT License.