Important

You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

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

Translation

There are 3 ways to translate content displayed in Oro applications to a user. You can use:

This topic explains when to use each of the three approaches and provides implementation examples.

Standard Symfony Translator

Pros

Cons

Does not require additional implementation and can be used in Symfony framework out-of-the-box.

Cannot be applied to translate dynamic content in the application.

The application you are developing is highly likely to contain some static content that is independent of any dynamic application data, is always displayed in the same place, and never changes. Examples of such content are labels of field forms, static text in the interface, flash messages, etc. Keep in mind this translation approach is used only for static content that does not have impact on any entity (entity field values).

To translate labels, use the Translation component, which is one of the main Symfony framework components.

Oro application adds the translation functionality on top of Symfony’s standard approach which enables modification of translations via UI.

To use this approach, add the translation file to the bundle: Resources/translations/messages.en.yml

1 oro:
2    translation:
3        some_field:
4            label: Localized value

Use the Symfony translator to translate a label in the twig template: Resources/views/Form/form.html.twig

1 {{ ‘oro.translation.some_field.label’|trans }}

or in the php code:

 1 <?php
 2
 3 namespace Oro\Bundle\AcmeBundle\Controller;
 4
 5 use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 6
 7 class AcmeController extends Controller
 8 {
 9     /**
10      * @return array
11      */
12     public function viewAction()
13     {
14         return [
15             'label' => $this->get('translator')->trans('oro.translation.some_field.label')
16         ];
17     }
18 }

More information on how to use it is available in Symfony Documentation.

Translatable Doctrine Extension

Pros

Cons

  • Dynamic content in the application can be easily translated.

  • The translatable fields have value related to the actual language of the application.

  • The user must switch the current language into the required language in the system configuration to fill in the fields with the required values.

  • Translatable fields can have values only for some languages but not for Localizations.

Dynamic content is another type of content used in Oro applications. What is displayed in the UI is based on data loaded from fixtures into the database and entered by users in the UI. As a rule, this data is based on dictionaries used in certain entities.

Examples of such data are the Country and Region fields which are used in the Address entity. The application has dictionaries for each of these entities with all available translations for all translatable fields of these entities (into all available languages). For instance, these fields must take into account the language selected for the interface in cases when users must be able to filter and sort data by Country and Region in a grid with addresses. In this case, use Gedmo/Translatable. Such fields are displayed in the UI in the selected language. All requests to the database will change in order for the translations grid to retrieve data based on the current locale.

Bellow is an example of an entity which must work with Gedmo/Translatable for the name field of this entity.

 1<?php
 2
 3namespace Oro\Bundle\AcmeBundle\Entity;
 4
 5use Doctrine\ORM\Mapping as ORM;
 6use Gedmo\Mapping\Annotation as Gedmo;
 7use Gedmo\Translatable\Translatable;
 8
 9/**
10 * @ORM\Table("oro_acme_country")
11 * @ORM\Entity()
12 * @Gedmo\TranslationEntity(class="Oro\Bundle\AcmeBundle\Entity\CountryTranslation")
13 */
14class Country implements Translatable
15{
16    /**
17     * @var string
18     *
19     * @ORM\Column(name="name", type="string", length=255)
20     * @Gedmo\Translatable
21     */
22    private $name;
23
24    /**
25     * @var string
26     *
27     * @Gedmo\Locale
28     */
29    private $locale;
30
31    /**
32     * @param string $name
33     */
34    public function setName(string $name)
35    {
36        $this->name = $name;
37    }
38
39    /**
40     * @return string
41     */
42    public function getName()
43    {
44        return $this->name;
45    }
46
47    /**
48     * @param string $locale
49     */
50    public function setLocale(string $locale)
51    {
52        $this->locale = $locale;
53    }
54
55    /**
56     * @return string
57     */
58    public function getLocale()
59    {
60        return $this->locale;
61    }
62}

Also, Gedmo/Translatable requires a dictionary with all translations for the original entity fields:

 1 <?php
 2
 3 namespace Oro\Bundle\AcmeBundle\Entity;
 4
 5 use Doctrine\ORM\Mapping as ORM;
 6 use Gedmo\Translatable\Entity\MappedSuperclass\AbstractTranslation;
 7
 8 /**
 9  * @ORM\Table(name="oro_acme_country_trans")
10  * @ORM\Entity()
11  */
12 class CountryTranslation extends AbstractTranslation
13 {
14     /**
15      * @var string
16      *
17      * @ORM\Column(type="string", length=255)
18      */
19     private $content;
20 }

For the grid to have working translations for entities with Gedmo fields, add the HINT_TRANSLATABLE hint: Resources/config/oro/datagrids.yml

1 datagrids:
2    acme-grid:
3        source:
4            type: orm
5            query:
6                ...
7            hints:
8                - HINT_TRANSLATABLE

Below is a simple example of a grid configuration which uses the hint: Resources/config/oro/datagrids.yml

 1 datagrids:
 2    acme-grid:
 3        source:
 4            type: orm
 5            query:
 6                select:
 7                    - country.id
 8                    - country.name
 9                from:
10                    - { table: Oro\Bundle\AcmeBundle\Entity\Country, alias: country }
11            hints:
12                - HINT_TRANSLATABLE
13
14        columns:
15            name:
16                label: Country Name
17
18        sorters:
19            columns:
20                name:
21                    data_name: country.name
22
23        filters:
24            columns:
25                name:
26                    type: string
27                    data_name: country.name

In this case, the values in the name field are displayed in the required language, and filtering and sorting for the values happens in the selected language.

LocalizedFallbackValue Entity from OroLocaleBundle

Pros

Cons

  • The translatable fields can be translated for each Localization available in the application.

  • It is easy to provide values for the Localizations in the entity form without changing the actual UI language.

  • Translated values cannot be used in the datagrids for filtering and sorting out-of-the-box.

  • Additional implementation is required to render translated values for the actual Localization.

UI language is incorporated into the localization entity. You can have several localizations in the application with the same interface language. However, data for various localizations may differ. In addition, if the current localization is assigned a parent localization then in cases when a field value does not exist, it is taken from the parent. This allows for setting up a flexible translation tree via the UI.

To implement this approach, use the LocalizedFallbackValue.

To use LocalizedFallbackValue for fields into the entity, make it is extendable:

 1 <?php
 2
 3 namespace Oro\Bundle\AcmeBundle\Entity;
 4
 5 use Doctrine\ORM\Mapping as ORM;
 6 use Oro\Bundle\AcmeBundle\Model\ExtendAcme;
 7
 8 /**
 9  * @ORM\Table(name="oro_acme")
10  * @ORM\Entity()
11  */
12 class Acme extends ExtendAcme
13 {
14     /**
15      * @ORM\ManyToMany(
16      *      targetEntity="Oro\Bundle\LocaleBundle\Entity\LocalizedFallbackValue",
17      *      cascade={"ALL"},
18      *      orphanRemoval=true
19      * )
20      * @ORM\JoinTable(
21      *      name="oro_acme_name",
22      *      joinColumns={
23      *          @ORM\JoinColumn(name="acme_id", referencedColumnName="id", onDelete="CASCADE")
24      *      },
25      *      inverseJoinColumns={
26      *          @ORM\JoinColumn(name="localized_value_id", referencedColumnName="id", onDelete="CASCADE", unique=true)
27      *      }
28      * )
29      */
30     protected $names;
31 }
 1 <?php
 2
 3 namespace Oro\Bundle\AcmeBundle\Model;
 4
 5 use Oro\Bundle\LocaleBundle\Entity\Localization;
 6 use Oro\Bundle\LocaleBundle\Entity\LocalizedFallbackValue;
 7
 8 /**
 9  * @method LocalizedFallbackValue getName(Localization $localization = null)
10  * @method LocalizedFallbackValue getDefaultName()
11  * @method void setDefaultName(string $value)
12  */
13 class ExtendAcme
14 {
15     public function __construct()
16     {
17     }
18 }

Enable Oro\Bundle\LocaleBundle\DependencyInjection\Compiler\DefaultFallbackExtensionPass for the entity and the field inside the bundle class:

 1 <?php
 2
 3 namespace Oro\Bundle\AcmeBundle;
 4
 5 use Oro\Bundle\AcmeBundle\Entity\Acme;
 6 use Oro\Bundle\LocaleBundle\DependencyInjection\Compiler\DefaultFallbackExtensionPass;
 7 use Symfony\Component\DependencyInjection\ContainerBuilder;
 8 use Symfony\Component\HttpKernel\Bundle\Bundle;
 9
10 class OroAcmeBundle extends Bundle
11 {
12     /**
13      * @param ContainerBuilder $container
14      */
15     public function build(ContainerBuilder $container)
16     {
17         parent::build($container);
18
19         $container->addCompilerPass(
20             new DefaultFallbackExtensionPass(
21                 [
22                     Acme::class => [
23                         'name' => 'names',
24                     ]
25                 ]
26             )
27         );
28     }
29 }

As the result, a proxy class is generated in the application cache: cache/prod/oro_entities/Extend/Entity/EX_OroAcmeBundle_Acme.php

 1 <?php
 2
 3 namespace Extend\Entity;
 4
 5 use Oro\Bundle\LocaleBundle\Entity\Localization;
 6 use Oro\Bundle\LocaleBundle\Entity\LocalizedFallbackValue;
 7
 8 abstract class EX_OroAcmeBundle_Acme extends \Oro\Bundle\LocaleBundle\Model\ExtendFallback implements \Oro\Bundle\EntityExtendBundle\Entity\ExtendEntityInterface
 9 {
10   /**
11    * @param Localization|null $localization
12    * @return LocalizedFallbackValue|null
13    */
14    public function getName(\Oro\Bundle\LocaleBundle\Entity\Localization $localization = NULL)
15    {
16        return $this->getFallbackValue($this->names, $localization);
17    }
18 }

To be able to provide translations in the UI, use the following example of the form type:

 1 <?php
 2
 3 namespace Oro\Bundle\AcmeBundle\Form\Type;
 4
 5 use Oro\Bundle\LocaleBundle\Form\Type\LocalizedFallbackValueCollectionType;
 6 use Symfony\Component\Form\AbstractType;
 7 use Symfony\Component\Form\FormBuilderInterface;
 8
 9 class AcmeType extends AbstractType
10 {
11     /**
12      * {@inheritdoc}
13      */
14     public function buildForm(FormBuilderInterface $builder, array $options)
15     {
16         $builder->add(
17             'names',
18             LocalizedFallbackValueCollectionType::class,
19             ['label' => 'oro.acme.names.label']
20         );
21     }
22 }

To retrieve a name for the Localization, it is enough to use the getName() method.

More Sources on Translations

Bundle Documentation

Business User Documentation

Media Library

SlideShare Translation and Localization Slides