Sonata Translation Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run:

   composer require ibrows/sonata-translation-bundle:dev-master
   

   Update AppKernel.php to include:

   new Lexik\Bundle\TranslationBundle\LexikTranslationBundle(),
   new Ibrows\SonataTranslationBundle\IbrowsSonataTranslationBundle(),
   

2. Basic Configuration Add minimal lexik_translation config in config.yml:

   lexik_translation:
       fallback_locale: en
   

3. Enable Translation in Sonata Admin Extend your admin class to support translations:

   use Ibrows\SonataTranslationBundle\Admin\TranslationAdminTrait;
   
   class YourAdmin extends AbstractAdmin
   {
       use TranslationAdminTrait;
   
       protected $translationDomain = 'messages'; // Optional: Override default domain
   }
   

4. First Use Case

   • Translate a field in Sonata Admin:

     $admin->addField('translations', 'sonata_type_translation', [
         'sourceField' => 'name', // Field to translate
         'editable' => true,
     ]);
     

Implementation Patterns

Workflows

1. Inline vs. Popup Mode

   • Inline: Edit translations directly in the admin grid (default).
   • Popup: Use a modal for translations (configure via editable.mode: popup).
   • Example: Switch to popup mode:

     ibrows_sonata_translation:
         editable:
             mode: popup
     

2. Field-Specific Translation Types Customize input types per field (e.g., select for dropdowns, date for dates):

   $admin->addField('translations', 'sonata_type_translation', [
       'type' => 'select', // Override default 'textarea'
       'options' => [
           'choices' => ['en' => 'English', 'fr' => 'French'],
       ],
   ]);
   

3. Bulk Translation Updates Use the TranslationAdminTrait to batch-edit translations via the Sonata Admin UI.

4. Integration with Custom Fields Extend sonata_type_translation for custom logic:

   $admin->addField('custom_translations', null, [
       'type' => 'ibrows_sonata_translation_custom',
       'options' => [
           'class' => 'AppBundle\Entity\CustomTranslation',
       ],
   ]);
   

Tips for Daily Use

• Default Domain: Set defaultDomain in config to avoid repeating translationDomain in every admin.
• Fallback Locale: Ensure lexik_translation.fallback_locale matches your app’s default locale.
• Translation Groups: Group translations by domain (e.g., messages, validation) for better organization.

Gotchas and Tips

Pitfalls

1. Missing LexikBundle

   • Error: Class 'Lexik\Bundle\TranslationBundle\LexikTranslationBundle' not found.
   • Fix: Ensure lexik/translation-bundle is installed (composer will auto-install it as a dependency).

2. Configuration Overrides

   • Issue: Custom editable settings not applying.
   • Debug: Verify ibrows_sonata_translation config is loaded after SonataAdminBundle.
   • Fix: Use imports in config.yml to enforce order:

     imports:
         - { resource: sonata_admin.yml }
         - { resource: ibrows_sonata_translation.yml }
     

3. Translation Field Not Rendering

   • Cause: Missing TranslationAdminTrait or incorrect field type.
   • Fix: Ensure the field uses sonata_type_translation:

     $admin->addField('translations', 'sonata_type_translation', [...]);
     

4. Locale-Specific Validation

   • Problem: Translations fail validation (e.g., empty required fields).
   • Solution: Add constraints to your translation entity or use emptytext config:

     ibrows_sonata_translation:
         editable:
             emptytext: "Translation required"
     

Debugging

• Check Logs: Enable debug mode (APP_DEBUG=true) to see if the bundle loads:

  php bin/console debug:config ibrows_sonata_translation
  

• Clear Cache: After config changes, run:

  php bin/console cache:clear
  

Extension Points

1. Custom Translation Types Create a new form type extending Ibrows\SonataTranslationBundle\Form\Type\TranslationType:

   namespace AppBundle\Form\Type;
   use Ibrows\SonataTranslationBundle\Form\Type\TranslationType as BaseType;
   
   class CustomTranslationType extends BaseType {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'custom_option' => true,
           ]);
       }
   }
   

   Register it as a service and reference it in your admin:

   'type' => 'app_custom_translation',
   

2. Override Templates Extend Sonata’s translation templates (e.g., block_translation_edit.html.twig) in templates/IbrowsSonataTranslationBundle/.

3. Dynamic Domains Use a callback to set the translation domain dynamically:

   use Ibrows\SonataTranslationBundle\Admin\TranslationAdminTrait;
   
   class DynamicAdmin extends AbstractAdmin {
       use TranslationAdminTrait;
   
       public function getTranslationDomain() {
           return $this->getSubject()->getDomain(); // Assume entity has getDomain()
       }
   }
   

Pro Tips

• Performance: For large datasets, lazy-load translations with Doctrine’s DISTINCT:

  $query->distinct();
  

• I18n Workflow: Combine with symfony/translation for runtime translations:

  $this->get('translator')->trans($translation->getKey(), [], null, $locale);
  

• Testing: Mock translations in PHPUnit:

  $this->get('lexik_translation.manager')->setFallbackLocale('test');