Laminas I18N Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install the package:

   composer require laminas/laminas-i18n
   

   (Note: Laravel developers typically use laminas/laminas-translator for translation-specific needs, but laminas-i18n provides broader i18n utilities like validation and filtering.)

2. Basic Translation Usage:

   use Laminas\Translator\Translator;
   
   $translator = new Translator();
   $translator->addTranslationFilePattern(
       'phpArray',
       __DIR__ . '/../language/%s/%s.php',
       'default',
       'en'
   );
   
   echo $translator->translate('greeting'); // Outputs: 'Hello!'
   

   (Place translation files in resources/lang/en/default.php with keys like 'greeting' => 'Hello!'.)

3. First Use Case:

   • Dynamic locale switching:

     $translator->setLocale('es'); // Switch to Spanish
     echo $translator->translate('greeting'); // Outputs: '¡Hola!'
     

Implementation Patterns

Core Workflows

1. Translation Management:

   • File-based translations: Use addTranslationFilePattern() for .php, .json, or .ini files.

     $translator->addTranslationFilePattern(
         'json',
         __DIR__ . '/../language/%s/%s.json',
         'default',
         'en'
     );
     

   • Plural/singular rules: Define in .php files:

     return [
         'items' => [
             'one'   => '1 item',
             'other' => '%d items',
         ],
     ];
     

     Use in code:

     $translator->translatePlural('items', 5); // Outputs: '5 items'
     

2. Validation Integration:

   • Reuse Laminas validators (e.g., EmailAddress, NotEmpty) with Laravel’s Validator facade:

     use Laminas\Validator\EmailAddress;
     
     $validator = new EmailAddress();
     if (!$validator->isValid('test@example.com')) {
         echo $validator->getMessages()->getFirst();
     }
     

3. Middleware for Locale:

   • Bind Translator to Laravel’s container and set locale via middleware:

     // app/Providers/AppServiceProvider.php
     public function register()
     {
         $this->app->singleton(Translator::class, function () {
             $translator = new Translator();
             $translator->addTranslationFilePattern(...);
             return $translator;
         });
     }
     
     // app/Http/Middleware/LocaleMiddleware.php
     public function handle($request, Closure $next)
     {
         app(Translator::class)->setLocale($request->header('Accept-Language') ?? 'en');
         return $next($request);
     }
     

4. Filtering User Input:

   • Use Laminas\Filter for locale-aware formatting:

     use Laminas\Filter\NumberFormat;
     
     $filter = new NumberFormat(['locale' => 'de_DE']);
     echo $filter->filter(1000.50); // Outputs: '1.000,50'
     

Laravel-Specific Tips

• Service Provider Binding: Extend Laravel’s AppServiceProvider to bind laminas-i18n components:

  $this->app->bind('laminas.translator', function () {
      return new Translator();
  });
  

• Blade Directives: Create a custom Blade directive for translations:

  // app/Providers/BladeServiceProvider.php
  Blade::directive('trans', function ($expression) {
      return "<?php echo app('laminas.translator')->translate({$expression}); ?>";
  });
  

  Usage in Blade:

  @trans('greeting')
  

• Configuration: Store translation paths in config/i18n.php:

  return [
      'paths' => [
          resource_path('lang/{locale}/'),
      ],
      'default_locale' => 'en',
  ];
  

Gotchas and Tips

Pitfalls

1. Locale Handling:

   • Empty string locale: Passing an empty string to setLocale() now throws an exception (fixed in v2.28.1). Validate locales:

     if (empty($locale)) $locale = 'en';
     

   • Fallback locale: Ensure Translator has a fallback locale set:

     $translator->setFallbackLocale('en');
     

2. Deprecated Components:

   • Laminas\I18n\Translator\TranslatorInterface was moved to laminas/laminas-translator in v2.27.0. Update imports:

     // Old (deprecated)
     use Laminas\I18n\Translator\TranslatorInterface;
     
     // New
     use Laminas\Translator\TranslatorInterface;
     

3. PHP Version Compatibility:

   • Drop support for PHP 8.0 in v2.23.0; ensure your Laravel app uses PHP 8.1+.

4. Validator Quirks:

   • Runtime mutation: Avoid modifying validator options after initialization (deprecated in v2.28.0).
   • Empty strings: Validators like IsFloat now return standardized error messages for empty inputs (fixed in v2.24.1).

5. Caching:

   • Translation files are not cached by default. Use laminas-cache for performance:

     use Laminas\Cache\Storage\Adapter\Filesystem;
     
     $cache = new Filesystem();
     $translator->setCache($cache);
     

Debugging Tips

1. Missing Translations:

   • Verify file paths and locales:

     $translator->getTranslationStorage()->hasTranslation('default', 'en', 'missing_key');
     

   • Check for typos in translation keys.

2. Validator Errors:

   • Inspect validator messages:

     $validator = new EmailAddress();
     if (!$validator->isValid($email)) {
         dd($validator->getMessages()->toArray());
     }
     

3. Performance:

   • Profile translation lookups with Xdebug or Laravel Telescope.
   • Avoid dynamic translation keys (e.g., $translator->translate($dynamicKey)).

Extension Points

1. Custom Translation Sources:

   • Implement Laminas\Translator\Translator\Loader\LoaderInterface for database-backed translations:

     class DatabaseLoader implements LoaderInterface {
         public function load($locale, $translationFile, $translationDomain) {
             return DB::table('translations')->where([...])->get();
         }
     }
     

2. Locale-Specific Logic:

   • Extend Laminas\I18n\Validator\AbstractValidator for custom rules:

     class CustomValidator extends AbstractValidator {
         public function isValid($value) {
             return !empty($value) && strlen($value) > 3;
         }
     }
     

3. Filter Chains:

   • Combine filters for complex transformations:

     use Laminas\Filter\FilterChain;
     use Laminas\Filter\StringToLower;
     use Laminas\Filter\StripTags;
     
     $filterChain = new FilterChain();
     $filterChain->attach(new StringToLower());
     $filterChain->attach(new StripTags());
     echo $filterChain->filter('<TAG>Hello</TAG>');
     

4. Testing:

   • Mock Translator in PHPUnit:

     $mockTranslator = $this->createMock(TranslatorInterface::class);
     $mockTranslator->method('translate')->willReturn('Mocked!');
     $this->app->instance(TranslatorInterface::class, $mockTranslator);