Oro Dictionary Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require algoritma/oro-dictionary-bundle
   

   Ensure your composer.json includes the package under require.

2. Cache & Translation Update:

   php bin/console cache:clear
   php bin/console oro:translation:update --force
   

3. Verify Integration: Check if Italian (it_IT) translations appear in the OroCommerce backend (e.g., admin UI, entity labels, or validation messages).

First Use Case

• Localize Entity Labels: Override default OroCommerce labels (e.g., Product, Order) in Italian by editing Resources/translations/messages.it_IT.yml (or create it if missing). Example:

  oro_product:
      entity_label: Prodotto
      entity_plural_label: Prodotti
  

Implementation Patterns

Workflows

1. Extending Translations:

   • Add new translations in Resources/translations/ (e.g., validation.it_IT.yml for validation messages).
   • Follow OroCommerce’s YAML structure:

     oro_customer:
         validation:
             email:
                 not_blank: "L'email non può essere vuota."
     

2. Dynamic Dictionary Updates:

   • Use the oro:translation:update command to reload translations after changes:

     php bin/console oro:translation:update --force
     

3. Integration with Custom Entities:

   • For custom entities, extend the bundle’s translation files or create new ones (e.g., AcmeDemoBundle/Resources/translations/messages.it_IT.yml).
   • Reference Oro’s translation keys (e.g., oro_entity.entity_label).

4. Localization in Templates:

   • Use Symfony’s trans filter in Twig:

     {{ 'oro_product.entity_label'|trans }}
     

Integration Tips

• Dependency Injection: The bundle leverages Oro’s translation system, so no custom services are required unless extending functionality.
• Testing: Test translations in the OroCommerce admin panel (e.g., navigate to System > Configuration > Localization).
• Fallbacks: Ensure English (en) translations exist as fallbacks for missing Italian keys.

Gotchas and Tips

Pitfalls

1. Cache Dependencies:

   • Forgetting to run cache:clear or oro:translation:update after adding new translations will result in stale UI text.
   • Fix: Always clear cache post-translation changes.

2. Key Conflicts:

   • Overwriting Oro’s core translation keys (e.g., oro_order.entity_label) may break system functionality.
   • Fix: Prefix custom keys (e.g., acme_custom.entity_label) or consult Oro’s documentation for safe overrides.

3. YAML Syntax Errors:

   • Invalid YAML in translation files will cause oro:translation:update to fail silently.
   • Fix: Validate with:

     php bin/console lint:yaml Resources/translations/
     

4. Language Scope:

   • The bundle only supports it_IT. For other languages, extend the bundle or use Oro’s built-in translation tools.

Debugging

• Missing Translations:

  • Check if the translation file exists in Resources/translations/ and the key matches Oro’s structure.
  • Use Symfony’s debug toolbar to inspect translation dumps.

• Translation Overrides Not Applying:

  • Verify the bundle is loaded in Resources/config/oro/bundles.yml:

    Algoritma\DictionaryBundle\AlgoritmaDictionaryBundle: ~
    

Extension Points

1. Custom Translation Domains:

   • Extend the bundle by adding new translation domains (e.g., oro_custom_domain) in Resources/config/oro/translations.yml.

2. Dynamic Language Switching:

   • Use Oro’s oro_locale system to toggle languages at runtime:

     $this->get('oro_locale.twig.extension')->setLocale('it_IT');
     

3. Contributing New Languages:

   • Fork the bundle and add new language files (e.g., messages.fr_FR.yml) following the existing structure.
   • Submit a PR to the repository.

Config Quirks

• No Config Files Required: The bundle auto-detects translations via Oro’s system, so no manual config.yml setup is needed.
• Bundle Order: Ensure AlgoritmaDictionaryBundle loads after OroPlatformBundle in bundles.yml to avoid initialization errors.