Translation Form Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require a2lix/translation-form-bundle baconmanager/translation-form-bundle
   

2. Register Bundles in app/AppKernel.php:

   new A2lix\TranslationFormBundle\A2lixTranslationFormBundle(),
   new BaconManager\TranslationFormBundle\BaconTranslationFormBundle(),
   

3. Configure config.yml:

   a2lix_translation_form:
       locale_provider: locale_doctrine_provider
       locales: [en_US, pt_BR]  # Optional if using dynamic provider
       default_locale: en_US
       manager_registry: doctrine
       templating: "BaconTranslationFormBundle::default.html.twig"
   
   bacon_translation_form:
       class_language_provider: AppBundle\Entity\Language  # Your custom Language entity
   

4. First Use Case Create a translatable entity (e.g., Product) with Translation embeddable and implement the bundle’s interfaces for your Language entity and repository as shown in the README.

Implementation Patterns

Workflow for Translatable Forms

1. Entity Setup Extend A2lix\TranslationFormBundle\Model\TranslatableInterface for your main entity (e.g., Product). Use A2lix\TranslationFormBundle\Model\Translation as an embeddable for translations.

2. Language Provider Implement Bacon\Bundle\TranslationFormBundle\Locale\EntityInterface for your Language entity (e.g., AppBundle\Entity\Language). Implement Bacon\Bundle\TranslationFormBundle\Locale\RepositoryInterface for the repository (e.g., AppBundle\Entity\Repository\LanguageRepository) with getAllLocale().

3. Form Type Use A2lix\TranslationFormBundle\Form\Type\TranslationsType in your form builder:

   $builder->add('translations', TranslationsType::class, [
       'fields' => ['name', 'description'], // Fields to translate
       'locales' => ['en_US', 'pt_BR'],     // Optional if using dynamic provider
   ]);
   

4. Twig Rendering Use the bundle’s Twig function to display language tabs:

   {{ render_language_tab(language, 'product.translations') }}
   

5. Saving Translations The EventListener (Bacon\Bundle\TranslationFormBundle\EventListener\TranslationListener) automatically tracks added/updated locales for each translatable entity.

Integration Tips

• Dynamic Locales: Rely on getAllLocale() from your repository to fetch locales dynamically, avoiding hardcoded locales in config.
• Caching: Leverage useResultCache in getAllLocale() to optimize performance (as shown in the example).
• Base Entity: Extend A2C\Bundle\CoreBundle\Entity\BaseEntity for your Language entity to reuse common traits (e.g., timestamps, slugs).
• Validation: Add validation constraints to your Language entity (e.g., @Assert\Length for locale/acron fields).

Gotchas and Tips

Pitfalls

1. Locale Provider Mismatch

   • Ensure locale_provider: locale_doctrine_provider in a2lix_translation_form config matches the bundle’s expectations.
   • If using a custom provider, verify it implements A2lix\TranslationFormBundle\Provider\LocaleProviderInterface.

2. Entity/Repository Interfaces

   • Forgetting to implement EntityInterface or RepositoryInterface will cause runtime errors. Double-check:

     use Bacon\Bundle\TranslationFormBundle\Locale\EntityInterface;
     use Bacon\Bundle\TranslationFormBundle\Locale\RepositoryInterface;
     

3. Caching Issues

   • The md5('bacon_cache_locale_provider') in getAllLocale() is hardcoded. Change it if you update your cache strategy (e.g., use a config parameter).

4. Twig Template Path

   • The default template path (BaconTranslationFormBundle::default.html.twig) must exist. Override it in config if needed:

     templating: "YourBundle::custom/translation.html.twig"
     

5. Event Listener Activation

   • The TranslationListener is auto-registered but requires the KnpDoctrineBehaviorsBundle (listed in AppKernel.php). Skip this bundle if you don’t need it.

Debugging Tips

1. Check Locale Provider Dump the provider in a controller to verify it returns expected locales:

   $provider = $this->get('a2lix_translation_form.locale_provider');
   dump($provider->getLocales());
   

2. Form Debugging Enable form theme debugging in Twig:

   {% form_theme _self with {'debug': true} %}
   

3. Doctrine Events Listen for prePersist/preUpdate events to debug translation tracking:

   $entityManager->getEventManager()->addEventListener(
       [ORM\Events::prePersist, ORM\Events::preUpdate],
       function ($event) {
           dump($event->getEntity());
       }
   );
   

Extension Points

1. Custom Twig Functions Extend the bundle’s Twig functions by overriding the template or adding new ones in your bundle’s Resources/views:

   {% macro render_custom_tab(language) %}
       <li>{{ language.acron }}</li>
   {% endmacro %}
   

2. Locale Filtering Modify getAllLocale() to filter active/inactive languages:

   public function getAllLocale() {
       $qb = $this->createQueryBuilder('l')
           ->where('l.isActive = :active')
           ->setParameter('active', true);
       return $qb->getQuery()->getResult();
   }
   

3. Translation Validation Add custom validation to the Translation embeddable:

   use Symfony\Component\Validator\Constraints as Assert;
   
   /**
    * @Assert\NotBlank(groups={"translation_validation"})
    */
   private $title;
   

4. Event Subscribers Extend the TranslationListener to add custom logic (e.g., logging):

   public function postPersist(LifecycleEventArgs $args) {
       $entity = $args->getObject();
       if ($entity instanceof TranslatableInterface) {
           $this->logger->info('Translations saved for ' . get_class($entity));
       }
   }