Cool Sonata Translation Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require coolshop/cool-sonata-translation-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   Coolshop\CoolSonataTranslationBundle\CoolSonataTranslationBundle::class => ['all' => true],
   

2. Basic Configuration Add minimal config in config/packages/cool_sonata_translation.yaml (Symfony 4+):

   cool_sonata_translation:
       defaultDomain: messages
       driver: orm
       localeManager: ['en', 'fr']  # Replace with your locales
   

3. First Use Case

   • Enable translations for a Sonata Admin entity by extending its CRUD controller:

     use Coolshop\CoolSonataTranslationBundle\Admin\TranslationAdminExtension;
     
     class YourAdmin extends AbstractCRUDController
     {
         public function configureTranslationFields(TranslationAdminExtension $extension)
         {
             $extension->addTranslationField('title', 'text'); // Field name, input type
         }
     }
     

   • Clear cache (php bin/console cache:clear) and visit the Sonata Admin panel.

Implementation Patterns

Workflow: Managing Translations

1. Field Translation Setup Define translatable fields in your admin class:

   $extension->addTranslationField('description', 'textarea')
             ->setEmptyText('No description')
             ->setOptions(['rows' => 5]);
   

2. Locale-Specific Logic Dynamically adjust translations per locale:

   $extension->setLocaleManager('@your_custom.locale_manager'); // Override default
   

3. Batch Operations Use the TranslationAdminExtension to bulk-edit translations:

   $extension->setEditableMode('popup'); // Switch between inline/popup
   

4. Integration with Forms Extend Symfony forms for translation-aware fields:

   $builder->add('translations', TranslationType::class, [
       'mapped' => false,
       'label' => 'Translations',
   ]);
   

Common Patterns

• Translation Domains: Group translations by domain (e.g., messages, validation) using defaultDomain or per-field:

  $extension->addTranslationField('field', 'text', 'custom_domain');
  

• Fallback Locales: Configure fallback chains in localeManager:

  localeManager: ['fr', 'en'] # 'en' as fallback for missing 'fr' translations
  

• Custom Drivers: Extend the ORM driver for non-DB storage (e.g., Redis):

  // services.yaml
  Coolshop\CoolSonataTranslationBundle\Driver\TranslationDriverInterface: '@your.redis_driver'
  

Gotchas and Tips

Pitfalls

1. Cache Dependencies

   • Issue: Translations may not update immediately after DB changes.
   • Fix: Clear Sonata cache:

     php bin/console sonata:cache:clear
     

   • Tip: Use cache:pool:clear sonata.cache.admin for targeted clearing.

2. Locale Manager Conflicts

   • Issue: localeManager service not found or misconfigured.
   • Fix: Verify the service ID exists (e.g., cool_sonata_translation.locale_manager.sonatapage) or use an array fallback:

     localeManager: ['en', 'fr'] # Array mode bypasses service lookup
     

3. ORM Driver Limitations

   • Issue: Only ORM driver is supported; Doctrine required.
   • Workaround: For non-Doctrine projects, create a custom driver implementing TranslationDriverInterface.

4. Field Type Mismatches

   • Issue: Unsupported input types (e.g., checklist requires extra config).
   • Fix: Register custom types in services.yaml:

     Coolshop\CoolSonataTranslationBundle\Form\Type\TranslationType:
         arguments:
             - ['text', 'textarea', 'your_custom_type']
     

Debugging Tips

• Enable Debug Mode: Add to config/packages/dev/cool_sonata_translation.yaml:

  debug: true
  

  Logs translation operations to var/log/dev.log.

• Check Event Listeners: Verify sonata.admin.event.DISPLAY listeners are active:

  php bin/console debug:event-dispatcher
  

Extension Points

1. Custom Translation Storage Override the ORM driver by binding a custom service:

   # config/services.yaml
   Coolshop\CoolSonataTranslationBundle\Driver\TranslationDriverInterface: '@app.custom_translation_driver'
   

2. UI Customization Extend Twig templates:

   {# Override translation field template #}
   @CoolSonataTranslation/translation/_field.html.twig
   

3. Validation Rules Add constraints to translation fields:

   $extension->addTranslationField('slug', 'text')
             ->addConstraint(new NotBlank());