Translation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation (despite deprecation, assume legacy project usage):

   composer require happyr/translation-bundle
   

   Register the bundle in config/bundles.php:

   Happyr\TranslationBundle\HappyrTranslationBundle::class => ['all' => true],
   

2. Configuration: Add to config/packages/happyr_translation.yaml:

   happyr_translation:
       api_key: '%env(LOCO_API_KEY)%'
       project_id: 'your_project_id'
       default_locale: 'en'
   

3. First Use Case: Fetch translations from Loco for a given locale:

   use Happyr\TranslationBundle\Service\TranslationService;
   
   $translations = $this->get('happyr_translation.translation_service')->getTranslations('fr');
   

Implementation Patterns

Core Workflows

1. Translation Sync:

   • Pull Translations:

     $service->syncTranslations('es'); // Syncs all missing/updated translations
     

   • Push New Strings:

     $service->pushTranslation('es', 'key', 'value');
     

2. Translation Loading:

   • Override Symfony’s translator to fetch from Loco:

     # config/services.yaml
     services:
         App\Translation\LocoTranslator:
             decorates: translator
             arguments:
                 $decorated: '@translator'
     

3. Domain-Specific Translations:

   • Use namespaces to organize translations:

     $service->getTranslations('de', 'admin'); // Fetches admin-specific keys
     

Integration Tips

• Cache Management: Cache translations in cache/ to avoid repeated API calls:

  happyr_translation:
      cache_enabled: true
      cache_lifetime: 3600 # 1 hour
  

• Fallback Logic: Combine Loco translations with local files:

  $translator->get('key', [], 'fr', 'messages'); // Falls back to `translations/messages.fr.yml`
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The bundle is deprecated in favor of php-translation/symfony-bundle. Migrate if possible.
   • No new features/bugfixes will be added.

2. API Rate Limits:

   • Loco’s API may throttle requests. Implement exponential backoff:

     try {
         $service->syncTranslations('ja');
     } catch (\GuzzleHttp\Exception\RequestException $e) {
         if ($e->getCode() === 429) {
             sleep(5); // Retry after delay
         }
     }
     

3. Locale Mismatches:

   • Ensure default_locale in config matches your app’s default (e.g., en). Loco may return unexpected keys if misconfigured.

Debugging

• Enable Logging:

  happyr_translation:
      debug: true
  

  Logs API responses to var/log/dev.log.

• Validate API Key: Test connectivity with:

  $service->ping(); // Returns true if API key is valid
  

Extension Points

1. Custom Translation Sources: Extend Happyr\TranslationBundle\Service\TranslationService to support additional providers (e.g., Crowdin):

   class CustomTranslationService extends TranslationService {
       public function getTranslations($locale, $domain = null) {
           // Override to fetch from Crowdin
       }
   }
   

2. Event Listeners: Hook into translation sync events:

   // src/EventListener/TranslationSyncListener.php
   public function onSync(TranslationSyncEvent $event) {
       $event->addTranslation('new_key', 'value');
   }
   

   Register in services.yaml:

   services:
       App\EventListener\TranslationSyncListener:
           tags:
               - { name: 'happyr_translation.sync_listener' }
   

3. Webhook Integration: Use Loco’s webhooks to auto-trigger syncs on translation updates:

   // src/Controller/LocoWebhookController.php
   public function handleWebhook(Request $request) {
       $this->get('happyr_translation.translation_service')->syncAllLocales();
   }