Common I18N Intl Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require binsoul/common-i18n-intl
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Binsoul\CommonI18nIntl\CommonI18nIntlServiceProvider::class,
   ],
   

2. Basic Usage Publish the config file (optional):

   php artisan vendor:publish --provider="Binsoul\CommonI18nIntl\CommonI18nIntlServiceProvider" --tag="config"
   

   Configure locales in config/common-i18n-intl.php:

   'locales' => [
       'en' => 'English',
       'es' => 'Spanish',
   ],
   

3. First Use Case: Localized Strings

   use Binsoul\CommonI18nIntl\Localizer;
   
   $localizer = app(Localizer::class);
   echo $localizer->get('en', 'greeting', ['name' => 'John']); // Loads from `resources/lang/en/greeting.php`
   

Implementation Patterns

Core Workflows

1. Locale Switching Dynamically set locale in middleware or controllers:

   $localizer->setLocale('es'); // Switches to Spanish
   

2. Pluralization & Genderization Leverage Intl for grammar-aware translations:

   $localizer->pluralize('en', 'item', 5); // Handles singular/plural forms
   $localizer->genderize('es', 'user', 'male'); // Gender-specific terms
   

3. Fallback Chains Configure fallback locales in config/common-i18n-intl.php:

   'fallbacks' => [
       'es' => ['ca'], // Catalan as fallback for Spanish
   ],
   

4. Date/Number Formatting Use the Formatter facade:

   use Binsoul\CommonI18nIntl\Facades\Formatter;
   
   $date = Formatter::formatDate('en', '2023-12-25', 'MMMM d, yyyy');
   $number = Formatter::formatNumber('de', 1234.56, '€#,##0.00');
   

Integration Tips

• Laravel Views: Bind the localizer to a view:

  return view('welcome', ['localizer' => $localizer]);
  

  {{ $localizer->get($locale, 'key', $vars) }}
  

• API Responses: Wrap responses in localized data:

  return response()->json([
      'message' => $localizer->get($request->locale, 'api.success')
  ]);
  

• Validation: Localize error messages:

  $messages = $localizer->get($locale, 'validation');
  $validator = Validator::make($data, $rules, $messages);
  

Gotchas and Tips

Pitfalls

1. Missing Locale Files

   • Error: Translation string not found.
   • Fix: Ensure locale files exist in resources/lang/{locale}/ and match the config.

2. Intl Extension Dependency

   • Error: Class 'IntlDateFormatter' not found.
   • Fix: Install the PHP Intl extension (pecl install intl) and restart the server.

3. Caching Headaches

   • Issue: Translations not updating after changes.
   • Fix: Clear Laravel cache (php artisan cache:clear) or disable caching in config:

     'cache' => false,
     

Debugging

• Log Missing Keys: Enable debug mode in config:

  'debug' => env('APP_DEBUG', false),
  

  Missing keys will log to storage/logs/laravel.log.

• Intl Errors: Use Intl::getErrorCode() and Intl::getErrorMessage() to diagnose Intl-specific issues.

Extension Points

1. Custom Formatters Extend the Formatter class to add locale-specific rules:

   class CustomFormatter extends Formatter {
       public function formatCustom($locale, $value) { ... }
   }
   

2. Override Localizer Bind a custom localizer in AppServiceProvider:

   $this->app->bind(Localizer::class, function ($app) {
       return new CustomLocalizer($app['config']);
   });
   

3. Add Locale Data Dynamically register locales at runtime:

   $localizer->registerLocale('pt', 'Português');
   

Performance Tips

• Preload Locales: Load all locales at boot for multi-lingual apps:

  $localizer->preloadLocales(['en', 'es', 'fr']);
  

• Avoid Repeated Lookups: Cache frequent translations:

  $localizer->remember('en', 'key', function () {
      return $localizer->get('en', 'key');
  }, 60); // Cache for 60 minutes