You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Security Support ends in January 2024. Read version 5.0 (the latest LTS version) of the Oro documentation to get the updated information.

See our Release Process documentation for more information on the currently supported and upcoming releases.


OroTranslationBundle enables a translation framework in the Oro applications and an integration with third-party translation services. Out-of-the-box, it provides integration with CrowdIn.

The bundle enables developers to define translation strings in the YAML configuration files and provides the translation management UI for users to manage languages and translations strings, synchronize translations between the Oro application and third-party services.

Translation Context Resolver

Translation context resolver should be used to humanize translation keys and give some additional info to developers and translators.

Classes Description

  • TranslationBundleExtensionTranslationContextResolverInterface - extensions interface for resolving Translation Context by translation key.


The context resolver must implement oro\Bundle\TranslationBundle\Extension\TranslationContextResolverInterface, for example:

namespace Oro\Bundle\TranslationBundle\Extension;

use Symfony\Contracts\Translation\TranslatorInterface;

 * Default context resolver
class TranslationContextResolver implements TranslationContextResolverInterface
    protected TranslatorInterface $translator;

    public function __construct(TranslatorInterface $translator)
        $this->translator = $translator;

     * {@inheritdoc}
    public function resolve($id)
         * Do something with key, for example parse key and based on parsed data prepare context string
        return $this->translator->trans('oro.translation.context.ui_label');

Context resolver should be registered with tag oro_translation.extension.translation_context_resolver, for example:

# default context resolver definition
    class: Oro\Bundle\TranslationBundle\Extension\TranslationContextResolver
        - '@translator'
        - { name: oro_translation.extension.translation_context_resolver, priority: -100 }

Form Types

Translation bundle provide form types for easier translation on frontend.

Form Types Description

  • translatable_entity

    This form type works exactly as regular entity form type, but it supports translatable entities and performs translation using one DB request.


    • class - entity class name, this option is required;
    • property - class property that should be used as label, by default string representation of entity will be used;
    • query_builder - custom query builder or callback to extract entities.
  • oro_select2_translatable_entity

    This form type is extended from translatable_entity and renders using Select2 JS widget with autocomplete.

Classes Description

  • TranslationBundle Form Type TranslatableEntityType - class for translatable_entity form type, provides functionality to work with translatable entities;
  • TranslationBundle Form DataTransformer CollectionToArrayTransformer - extends standard Doctrine transformer to support empty array as data source.


        arguments: ["@doctrine"]
            - { name: form.type, alias: translatable_entity }

        parent: oro_form.type.select2
        arguments: ["translatable_entity"]
            - { name: form.type, alias: oro_select2_translatable_entity }

Translation Strategies

Translation bundle provides mechanism of translation strategies to handle translation fallbacks. Each strategy provides locale fallback tree that describes which locales must be used as fallback locale for each source fallback. Here is example of such tree:

    'en' => [
        'en_US' => [
            'en_CA' => [],
            'en_MX' => [],
        'en_CA' => [],
        'en_GB  => [],

Current strategy can be extracted from strategy provider - this class is used to store selected strategy and perform some additional manipulations with it. Translator uses strategy provider and current strategy to handle translation fallbacks.

Classes Description

  • TranslationBundle\Strategy\TranslationStrategyInterface

    Main interface for translation strategies.


    • getName - returns text identifier of the strategy;
    • getLocaleFallbacks - returns tree of locale fallbacks.
  • TranslationBundle\Strategy\DefaultTranslationStrategy

    Implementation of TranslationStrategyInterface to handle default one-locale translation fallback.

  • TranslationBundle\Strategy\TranslationStrategyProvider

    The main purpose of this class is storing of current translation strategy and performing additional manipulations with it.


    • getStrategy - returns current strategy;
    • setStrategy - sets specified strategy as current;
    • getFallbackLocales - returns list of allowed fallback locales for specified strategy and source locale;
    • getAllFallbackLocales - returns list of all fallback locales for specified strategy.

Dependency Injection Tags

  • oro_translation.extension.translation_strategy - Registers strategy for providing translation locale fallbacks. Strategy must implement TranslationStrategyInterface.

Related Documentation