Translator Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dahovitech/translator-bundle
   

   Register in config/bundles.php (if not using Flex):

   Dahovitech\TranslatorBundle\DahovitechTranslatorBundle::class => ['all' => true],
   

2. Configure: Create config/packages/dahovitech_translator.yaml with basic settings:

   dahovitech_translator:
       locales: ['en', 'fr']
       default_locale: 'en'
       domains: ['messages']
   

3. Migrate DB:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

4. First Use Case: Inject TranslationManager in a controller/service:

   use Dahovitech\TranslatorBundle\Service\TranslationManager;
   
   public function __construct(private TranslationManager $manager) {}
   
   // Set a translation
   $this->manager->setTranslation('welcome', 'fr', 'Bienvenue !', 'messages');
   

Implementation Patterns

Core Workflows

1. Translation Management:

   // CRUD operations
   $this->manager->setTranslation('key', 'locale', 'content', 'domain');
   $translation = $this->manager->getTranslation('key', 'locale', 'domain');
   $exists = $this->manager->hasTranslation('key', 'locale', 'domain');
   $this->manager->removeTranslation('key', 'locale', 'domain');
   

2. Bulk Operations:

   // Import/export
   $this->manager->importTranslations(['key1' => 'val1'], 'fr', 'messages');
   $translations = $this->manager->exportTranslations('fr', 'messages');
   

3. API Integration: Use endpoints like:

   GET /api/translations?locale=fr&domain=messages
   POST /api/translations/import (with JSON payload)
   

Integration Tips

• Symfony Translator Compatibility: Use standard trans() calls—this bundle acts as a backend:

  {{ 'welcome'|trans({}, 'messages', 'fr') }}
  

• Event-Driven Workflows: Extend with Symfony events (e.g., kernel.request) to auto-detect missing translations:

  $missing = $this->manager->findMissingTranslations('fr', 'en');
  

• Cache Optimization: Enable caching in config (enable_cache: true) and leverage cache_ttl for API responses.

Gotchas and Tips

Pitfalls

1. Locale/Domain Mismatches:

   • Always specify domain (e.g., 'messages') to avoid silent fallback to default locale.
   • Debug missing translations with:

     $this->manager->findMissingTranslations('fr', 'en');
     

2. API Rate Limiting:

   • Disable enable_api temporarily during heavy imports to avoid conflicts.

3. Migration Conflicts:

   • If modifying the dahovitech_translations table, drop and recreate migrations:

     php bin/console doctrine:migrations:diff --force
     

Debugging Tips

• Log Missing Translations: Add a subscriber to log missing translations during requests:

  public function onKernelRequest(GetResponseEvent $event) {
      $missing = $this->manager->findMissingTranslations('fr', 'en');
      if (!empty($missing)) {
          $this->logger->warning('Missing translations:', $missing);
      }
  }
  

• Cache Invalidation: Clear cache after bulk imports:

  php bin/console cache:clear
  

Extension Points

1. Custom Importers: Extend TranslationManager to support new formats (e.g., CSV):

   $this->manager->importFromCsv('path/to/file.csv', 'fr', 'messages');
   

2. Domain-Specific Logic: Override TranslationRepository to add domain-specific validation:

   public function save(Translation $translation) {
       if ($translation->getDomain() === 'security') {
           $this->validateSecurityTranslation($translation);
       }
       parent::save($translation);
   }
   

3. API Authentication: Secure API endpoints with Symfony’s security system:

   # config/packages/security.yaml
   firewalls:
       api:
           pattern: ^/api/translations
           guard:
               authenticators:
                   - your_custom_authenticator