Platform Locale Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require digitalstate/platform-locale-bundle
   

   Register it in config/bundles.php:

   return [
       // ...
       DigitalState\PlatformLocaleBundle\DigitalStatePlatformLocaleBundle::class => ['all' => true],
   ];
   

2. Enable OroLocaleBundle Dependency Ensure oro/locale-bundle is installed and configured as this bundle extends its functionality:

   composer require oro/locale-bundle
   

3. First Use Case: Localized Entity Attributes in Twig Use the localized_value Twig filter to display localized entity attributes dynamically:

   {{ entity.title|localized_value }}
   

   Ensure your entity has a getTranslations() method (Oro-compatible) or a localizedFields configuration.

Implementation Patterns

Core Workflows

1. Dynamic Localization in Views

   • Use the Twig extension for real-time localization without hardcoding translations:

     {% for product in products %}
         <h3>{{ product.name|localized_value }}</h3>
         <p>{{ product.description|localized_value }}</p>
     {% endfor %}
     

   • Pass the current locale via the request (e.g., app.request.locale).

2. Integration with OroPlatform

   • Leverage Oro’s Localization system for entity translations. Example entity setup:

     // src/Entity/Product.php
     use Oro\ORM\Mapping as ORM;
     
     #[ORM\Entity]
     class Product {
         #[ORM\ManyToMany(targetEntity: Translation::class)]
         #[ORM\JoinColumn(fieldName: "translations")]
         private $translations;
     }
     

3. Customizing Localized Fields

   • Define which fields to localize in your entity’s metadata (Oro-style):

     # config/oro/locale.yml
     oro_locale:
         localized_fields:
             - { entity: App\Entity\Product, field: name }
             - { entity: App\Entity\Product, field: description }
     

4. Service-Based Localization

   • Inject the DigitalState\PlatformLocaleBundle\Twig\LocalizedValueExtension service for programmatic use:

     use DigitalState\PlatformLocaleBundle\Twig\LocalizedValueExtension;
     
     class MyService {
         public function __construct(
             private LocalizedValueExtension $localizedValueExtension
         ) {}
     
         public function getLocalizedTitle($entity) {
             return $this->localizedValueExtension->getLocalizedValue($entity, 'title');
         }
     }
     

Gotchas and Tips

Pitfalls

1. Missing OroLocaleBundle

   • Error: Class 'Oro\Bundle\LocaleBundle\...' not found.
   • Fix: Install oro/locale-bundle and ensure it’s registered in bundles.php.

2. Incorrect Entity Translation Structure

   • Error: localized_value filter returns null or throws UndefinedIndexException.
   • Fix: Verify your entity follows Oro’s translation pattern (e.g., getTranslations() method or localizedFields config).

3. Locale Not Detected

   • Error: Localized values default to the entity’s "base" locale instead of the request locale.
   • Fix: Ensure the request locale is set (e.g., via middleware or Oro’s locale listener):

     // app/Http/Middleware/SetLocale.php
     public function handle($request, Closure $next) {
         app('oro_locale')->setLocale($request->getPreferredLanguage());
         return $next($request);
     }
     

Debugging Tips

1. Check Available Locales Dump Oro’s configured locales to verify setup:

   dd(app('oro_locale')->getAvailableLocales());
   

2. Inspect Entity Translations Debug the raw translations for an entity:

   $entity = $entityManager->getRepository(Product::class)->find(1);
   dd($entity->getTranslations()->toArray());
   

3. Override Twig Extension Extend the LocalizedValueExtension to add custom logic:

   // src/Twig/ExtendedLocalizedValueExtension.php
   use DigitalState\PlatformLocaleBundle\Twig\LocalizedValueExtension;
   
   class ExtendedLocalizedValueExtension extends LocalizedValueExtension {
       public function getLocalizedValue($entity, $field, $locale = null) {
           $value = parent::getLocalizedValue($entity, $field, $locale);
           return strtoupper($value); // Example: Force uppercase
       }
   }
   

   Register it in services.yaml:

   services:
       app.twig.localized_value_extension:
           class: App\Twig\ExtendedLocalizedValueExtension
           tags: ['twig.extension']
   

Performance

• Caching: Oro’s translations are cached by default. Clear the cache after adding new locales:

  php bin/console cache:clear
  

• Eager Loading: Use DQL JOIN to fetch translations upfront and avoid N+1 queries:

  $query = $entityManager->createQuery('SELECT p, t FROM App\Entity\Product p JOIN p.translations t WHERE t.locale = :locale');
  $query->setParameter('locale', $request->getLocale());