I18N Doctrine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require arsigor/i18n-doctrine-bundle
   

   Ensure a2lix/translation-form-bundle is also installed (required dependency).

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Arsigor\I18nDoctrineBundle\ArsigorI18nDoctrineBundle::class => ['all' => true],
       A2lix\TranslationFormBundle\A2lixTranslationFormBundle::class => ['all' => true],
   ];
   

3. Configure Doctrine Update config/packages/doctrine.yaml:

   doctrine:
       orm:
           mappings:
               App:
                   is_bundle: false
                   type: attribute
                   dir: "%kernel.project_dir%/src/Entity"
                   prefix: "App\Entity"
                   alias: App
   

4. First Use Case: Translatable Entity Create a translatable entity (e.g., Product):

   use Arsigor\I18nDoctrineBundle\Annotation as I18n;
   use Doctrine\ORM\Mapping as ORM;
   
   #[ORM\Entity]
   #[I18n\Translatable]
   class Product
   {
       #[ORM\Id, ORM\GeneratedValue]
       #[ORM\Column]
       private ?int $id = null;
   
       #[I18n\TranslationFields]
       private array $translations = [];
   
       // Getters/setters...
   }
   

5. Generate Translations Run the bundle’s command to scaffold translation fields:

   php bin/console arsigor:i18n:generate-translations App\Entity\Product
   

Implementation Patterns

Workflow: Managing Translations

1. Define Translatable Fields Use annotations to mark fields for translation:

   #[I18n\TranslationField("name")]
   #[I18n\TranslationField("description")]
   private array $translations = [];
   

2. Form Integration Use A2lixTranslationFormBundle to handle translations in forms:

   use Symfony\Bridge\Doctrine\Form\Type\EntityType;
   use A2lix\TranslationFormBundle\Form\Type\TranslationsType;
   
   $builder->add('translations', TranslationsType::class, [
       'fields' => ['name', 'description'],
       'locales' => ['en', 'fr'],
   ]);
   

3. Repository Patterns Query translations efficiently:

   $product = $entityManager->getRepository(Product::class)
       ->findOneBy(['id' => 1], ['translations' => 'en']);
   

4. Validation Add constraints to translatable fields:

   use Symfony\Component\Validator\Constraints as Assert;
   
   #[I18n\TranslationField("name")]
   #[Assert\NotBlank(groups: ['translation_validation'])]
   private array $translations = [];
   

5. API Responses Normalize translations in serializers (e.g., API Platform):

   use Arsigor\I18nDoctrineBundle\Serializer\Normalizer\TranslatableNormalizer;
   
   #[Serializer\Normalizer\Context(['groups' => ['translations']])]
   public function getTranslations(): array
   {
       return $this->translations;
   }
   

Gotchas and Tips

Pitfalls

1. Missing A2lixTranslationFormBundle

   • Symptom: Forms fail to render translations.
   • Fix: Ensure a2lix/translation-form-bundle is installed and configured.

2. Locale Not Found

   • Symptom: InvalidArgumentException when querying unsupported locales.
   • Fix: Validate locales in config/packages/arsigor_i18n.yaml:

     arsigor_i18n:
         locales: ['en', 'fr', 'de']
     

3. Translation Field Overrides

   • Symptom: Custom getters/setters break translation logic.
   • Fix: Avoid overriding getTranslations()/setTranslations() unless extending the bundle.

4. Doctrine Migrations

   • Symptom: Manual schema changes break translation tables.
   • Fix: Use the bundle’s migration generator:

     php bin/console doctrine:migrations:generate
     

Debugging Tips

1. Check Generated SQL Enable Doctrine logging to verify queries:

   doctrine:
       dbal:
           logging: true
           profiling: true
   

2. Validate Annotations Use PHPStan or Psalm to catch annotation errors early.

3. Clear Cache After Changes

   php bin/console cache:clear
   

Extension Points

1. Custom Translation Storage Override the default TranslationStorage service to use a custom backend (e.g., Redis):

   services:
       Arsigor\I18nDoctrineBundle\Storage\TranslationStorage:
           arguments:
               $cache: '@redis.client'
   

2. Dynamic Locale Handling Extend the TranslatableListener to add runtime locale logic:

   use Arsigor\I18nDoctrineBundle\EventListener\TranslatableListener;
   
   class CustomTranslatableListener extends TranslatableListener
   {
       public function onLoad(LoadClassMetadataEventArgs $event): void
       {
           // Custom logic here
           parent::onLoad($event);
       }
   }
   

3. Fallback Locales Configure fallback locales in arsigor_i18n.yaml:

   arsigor_i18n:
       fallback_locale: 'en'