SonataAdminBundle/Resources/doc/reference/translation.rst

Translation
===========

There are two main catalogue names in an Admin class:

* ``SonataAdminBundle`` : this catalogue is used to translate shared messages accross different admin
* ``messages`` : this catalogue is used to translate the message for the current admin

Ideally the ``messages`` catalogue should be changed to avoid any issues with other Admin classes.

You have two options to configure the catalogue for the admin class:

* one by defining a property

.. code-block:: php

    <?php
    class PageAdmin extends Admin
    {
        protected $translationDomain = 'SonataPageBundle';
    }


* or by injecting the value through the container

.. code-block:: xml

        <service id="sonata.page.admin.page" class="Sonata\PageBundle\Admin\PageAdmin">
            <tag name="sonata.admin" manager_type="orm" group="sonata_page" label="page"/>
            <argument />
            <argument>Application\Sonata\PageBundle\Entity\Page</argument>
            <argument />

            <call method="setTranslationDomain">
                <argument>SonataPageBundle</argument>
            </call>
        </service>


An admin instance always get the ``translator`` instance, so it can be used to translate messages within the
``configure*Fields`` method or in templates.

.. code-block:: jinja

    {# the classical call by using the twig trans helper #}
    {% trans from 'SonataPageBundle'%}message_create_snapshots{% endtrans %}

    {# by using the admin trans method with hardcoded catalogue #}
    {{ admin.trans('message_create_snapshots', {}, 'SonataPageBundle') }}

    {# by using the admin trans with the configured catalogue #}
    {{ admin.trans('message_create_snapshots') }}


The later solution is more flexible as no catalogue parameters are hardcoded.

Translate field labels
----------------------

The Admin bundle comes with a customized form field template. The most notable changes from the original one is the use
of the translation domain provided by the Admin instance to translate label.

By default, the label is the the field name. However a label can be defined as a the third argument of the ``add`` method:

.. code-block:: php

    <?php
    class PageAdmin extends Admin
    {
        public function configureFormFields(FormMapper $formMapper)
        {
            $formMapper->add('isValid', null, array('required' => false, 'label' => 'label.is_valid'));
        }
    }

There is another option for rapid prototyping or to avoid spending too much time adding the ``label`` key to all option
fields: ``Label Strategies``. By default labels are generated by using by using a simple rule ::

    isValid => Isvalid

This is not perfect and hard to read. So in order to solve this, the ``AdminBundle`` comes with different key label generation
strategies:

* ``sonata.admin.label.strategy.form_component`` : The default behavior from the Form Component - ``isValid`` => ``Isvalid``)
* ``sonata.admin.label.strategy.underscore`` : Add undescore to the label  - ``isValid`` => ``label_is_valid``
* ``sonata.admin.label.strategy.native`` : Make the string human readable readable - ``isValid`` => ``Is Valid``
* ``sonata.admin.label.strategy.noop`` : does not alter the string - ``isValid`` => ``isValid``

``sonata.admin.label.strategy.underscore`` will be better for i18n applications and ``sonata.admin.label.strategy.native`
will be better for native language based on the field name. So it is possible to start with the ``native`` strategy and then
when the application need to be translated using generic keys the configuration can be switched to used the ``sonata.admin.label.strategy.underscore``.

The strategy can be quickly configured when the Admin class is registered into the Container:

.. code-block:: xml

        <service id="ekino.project.admin.security_feed" class="AcmeBundle\ProjectBundle\Admin\ProjectAdmin">
            <tag name="sonata.admin" manager_type="orm" group="Project" label="Project" label_translator_strategy="sonata.admin.label.strategy.native" />
            <argument />
            <argument>AcmeBundle\ProjectBundle\Entity\ProjectFeed</argument>
            <argument />
        </service>

.. note::

    In all cases the label will be used by the ``Translator``. The strategy is just a quick way to generate translable keys
    depends on the project's requirements.