Laminas Translator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laminas/laminas-translator
   

   • No runtime dependencies beyond PHP 8.0+.

2. First Use Case:

   • Type-hint the Laminas\Translator\TranslatorInterface in your service or controller:

     use Laminas\Translator\TranslatorInterface;
     
     class MyService {
         public function __construct(private TranslatorInterface $translator) {}
     }
     

   • This allows dependency injection of any Laminas-compatible translator (e.g., Laminas\I18n\Translator\Translator) without coupling to laminas-i18n.

3. Where to Look First:

   • Laminas I18n Documentation for implementation details.
   • TranslatorInterface source: Laminas/Translator/TranslatorInterface.php.

Implementation Patterns

Core Workflows

1. Dependency Injection:

   • Use the interface in Laravel’s service container (via custom binding):

     $app->bind(TranslatorInterface::class, function ($app) {
         return new \Laminas\I18n\Translator\Translator();
     });
     

   • For Laminas MVC, leverage the built-in TranslatorFactory.

2. Translation Logic:

   • Basic translation:

     $translator->translate('Hello, %name!', ['name' => 'World']);
     

   • Text domains (e.g., messages, validation):

     $translator->translate('Invalid email', 'validation');
     

3. Adapter Integration:

   • Use adapters like Laminas\I18n\Translator\Adapter\Gettext or ArrayAdapter:

     $adapter = new \Laminas\I18n\Translator\Adapter\ArrayAdapter([
         'Hello' => 'Hola',
     ]);
     $translator->addTranslationSource($adapter);
     

4. Locale Management:

   • Set default locale:

     $translator->setLocale('es_ES');
     

   • Runtime switching:

     $translator->setLocale($request->getPreferredLanguage());
     

Laravel-Specific Patterns

1. Facade Integration (Custom):

   • Create a facade to bridge Laminas’ translator with Laravel’s trans() helper:

     class LaminasTranslatorFacade extends \Illuminate\Support\Facades\Facade {
         protected static function getFacadeAccessor() {
             return app(TranslatorInterface::class);
         }
     }
     

   • Register in AppServiceProvider:

     public function register() {
         $this->app->singleton(TranslatorInterface::class, function () {
             return new \Laminas\I18n\Translator\Translator();
         });
     }
     

2. View Integration:

   • Extend Laravel’s @lang directive or use a custom Blade component:

     Blade::directive('laminasLang', function ($expression) {
         return "<?php echo app('translator')->translate($expression); ?>";
     });
     

     Usage:

     @laminasLang('Hello')
     

3. Validation Messages:

   • Override Laravel’s validation messages with Laminas’ translator:

     $validator = Validator::make($data, $rules);
     $validator->setTranslator(function ($message, $attribute, $rule, $parameters) {
         return app(TranslatorInterface::class)->translate($message, 'validation');
     });
     

Gotchas and Tips

Pitfalls

1. Breaking Changes in 2.0.0:

   • The TranslatorInterface now uses native parameter/return types (e.g., string translate(string $id, array $text = [], string $locale = null, string $domain = null)).
   • Impact: Adapters or custom implementations relying on dynamic method calls (e.g., __invoke) may break. Test thoroughly.

2. No Laravel/Symfony Integration:

   • The package does not provide Laravel Facades or Symfony bridges. You must build these manually, increasing boilerplate.

3. Low Community Support:

   • With 3 GitHub stars and no active contributors, validate alternatives (e.g., voku/translation, symfony/translation) if maintenance is a concern.

4. Pluralization Quirks:

   • Laminas’ pluralization rules may differ from Laravel’s. Test edge cases (e.g., Arabic, Russian) early:

     $translator->translatePlural(
         '%count% item',
         '%count% items',
         $count,
         'messages'
     );
     

5. Adapter Conflicts:

   • If using multiple adapters, ensure translation sources are merged correctly. Overlapping keys may cause unexpected behavior.

Debugging Tips

1. Check Locale Fallbacks:

   • If translations are missing, verify the locale chain:

     $translator->getLocale(); // Current locale
     $translator->getFallbackLocale(); // Fallback chain
     

2. Inspect Translation Sources:

   • List all loaded adapters:

     $sources = $translator->getTranslationSources();
     print_r($sources);
     

3. Enable Debug Mode:

   • For Laminas’ Translator, set:

     $translator->setDebug(true);
     

   • This logs missing translations and adapter calls.

4. Handle Missing Translations:

   • Configure a fallback for untranslated strings:

     $translator->setDefaultTextDomain('messages');
     $translator->setFallbackLocale('en_US');
     

Extension Points

1. Custom Adapters:

   • Implement Laminas\I18n\Translator\Adapter\AdapterInterface for new translation sources (e.g., API-based translations):

     class ApiTranslationAdapter implements AdapterInterface {
         public function isEmpty(): bool { /* ... */ }
         public function translate($message, $locale, $textDomain): string { /* ... */ }
     }
     

2. Pluralization Rules:

   • Override default rules by extending Laminas\I18n\Translator\TextDomain\TextDomain:

     class CustomTextDomain extends TextDomain {
         protected function getPluralRule($locale): string {
             return 'custom rule for ' . $locale;
         }
     }
     

3. Caching Layer:

   • Wrap the translator in a caching decorator (e.g., using Laminas\Cache):

     $cache = new \Laminas\Cache\Storage\Adapter\Memory();
     $translator = new \Laminas\I18n\Translator\Translator();
     $cachedTranslator = new \Laminas\I18n\Translator\Translator\CachedTranslator($translator, $cache);
     

4. Laravel Service Provider:

   • Extend Laravel’s AppServiceProvider to bind the translator with caching:

     public function register() {
         $this->app->singleton(TranslatorInterface::class, function ($app) {
             $translator = new \Laminas\I18n\Translator\Translator();
             $translator->setCache(new \Illuminate\Cache\Repository($app['cache']));
             return $translator;
         });
     }
     

Config Quirks

1. Text Domain Defaults:

   • The DEFAULT_TEXT_DOMAIN constant ('default') may conflict with Laravel’s default domain ('messages'). Explicitly set domains:

     $translator->translate('key', 'messages');
     

2. Locale Negotiation:

   • Laminas’ locale negotiation differs from Laravel’s. Use middleware to set the locale:

     public function handle($request, Closure $next) {
         app(TranslatorInterface::class)->setLocale($request->getPreferredLanguage());
         return $next($request);
     }
     

3. Adapter Priority:

   • Adapters are checked in registration order. Prioritize critical adapters first:

     $translator->addTranslationSource($primaryAdapter);
     $translator->addTranslationSource($fallbackAdapter);