Laminas I18N Laravel Package

Getting Started

Minimal Setup in Laravel

1. Installation:

   composer require laminas/laminas-i18n
   

   Laravel developers typically integrate this via Service Providers or Facades (if wrapping the package).

2. Basic Translation Usage:

   use Laminas\Translator\Translator;
   
   $translator = new Translator();
   $translator->addTranslationFilePattern(
       'phpArray',
       __DIR__ . '/../language/*',
       'default'
   );
   
   echo $translator->translate('greeting.hello'); // Outputs translated string
   

3. First Use Case:

   • Load translations from .php/.json files (e.g., resources/lang/en/messages.php).
   • Use in Blade templates:

     {{ trans('messages.welcome') }}
     

Implementation Patterns

Core Workflows

1. Translation Loading:

   • File Formats: Supports .php, .json, .ini, .csv, .xliff.
   • Pattern-Based Loading:

     $translator->addTranslationFilePattern(
         'json',
         base_path('resources/lang/{locale}/messages.json'),
         'messages'
     );
     

   • Dynamic Locale Switching:

     $translator->setLocale('fr_FR');
     

2. Pluralization:

   • Handle language-specific plural rules (e.g., Russian, Arabic):

     $translator->translatePlural(
         'item',
         'items',
         5,
         'en_US'
     );
     

3. Validation/Filtering:

   • Use built-in validators (e.g., EmailAddress, PostCode) or filters (e.g., NumberParse):

     use Laminas\Validator\EmailAddress;
     $validator = new EmailAddress();
     $validator->isValid('test@example.com');
     

4. Caching Translations:

   • Cache translations for performance (requires laminas/laminas-cache):

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

Laravel-Specific Integration

• Service Provider:

  public function register()
  {
      $this->app->singleton('translator', function ($app) {
          $translator = new Translator();
          $translator->addTranslationFilePattern(
              'phpArray',
              base_path('resources/lang/{locale}'),
              'messages'
          );
          return $translator;
      });
  }
  

• Facade Wrapper (Optional):

  // app/Facades/Translator.php
  namespace App\Facades;
  use Illuminate\Support\Facades\Facade;
  class Translator extends Facade { protected static function getFacadeAccessor() { return 'translator'; } }
  

Gotchas and Tips

Pitfalls

1. Locale Handling:

   • Empty string locales now throw exceptions (since v2.28.1). Validate locales:

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

2. Deprecated Interfaces:

   • Laminas\I18n\Translator\TranslatorInterface is deprecated. Use Laminas\Translator\TranslatorInterface instead.

3. PHP Version Compatibility:

   • Drop support for PHP 8.0 in v2.23.0. Ensure your Laravel app uses PHP ≥8.1.

4. Validator Options:

   • Runtime mutation of validator options is deprecated (v2.28.0). Pre-configure options:

     $validator = new EmailAddress(['allow' => true]);
     

Debugging Tips

• Missing Translations:

  • Verify file paths in addTranslationFilePattern() match your Laravel resources/lang structure.
  • Check for typos in translation keys (case-sensitive).

• Pluralization Issues:

  • Test with known plural rules (e.g., 1 item, 2 items). Use translatePlural() for debugging:

    $translator->translatePlural('key', 'key_plural', 1, 'ru_RU');
    

• Caching Problems:

  • Clear cache if translations aren’t updating:

    $cache->clear();
    

Extension Points

1. Custom Validators/Filters:

   • Extend Laminas\Validator\AbstractValidator or Laminas\Filter\AbstractFilter:

     class CustomValidator extends AbstractValidator {
         public function isValid($value) { /* ... */ }
     }
     

2. Translation File Formats:

   • Implement Laminas\Translator\Translator\Loader\LoaderInterface for custom formats (e.g., YAML).

3. Locale Data:

   • Override default locale data (e.g., country codes) via dependency injection:

     $translator->setLocaleData(new \Laminas\I18n\Locale\DataArray());
     

Performance

• Avoid Over-Fetching:
  • Load only necessary translation files (e.g., split by domain/module).
• Cache Aggressively:
  • Use laminas/laminas-cache with a persistent store (e.g., Redis) for production.