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 admins
* ``messages`` : this catalogue is used to translate the messages 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 gets 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 field name. However a label can be defined as 
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 a simple rule ::

    isValid => Is Valid

.. note::

    For early adopter, you can use a specific backward compatible service to 
    keep your current translation.

The ``AdminBundle`` comes with different key label generation strategies:

* ``sonata.admin.label.strategy.native`` : DEFAULT - Makes the string human 
    readable readable - ``isValid`` => ``Is Valid``
* ``sonata.admin.label.strategy.form_component`` : The default behavior from the
    Form Component - ``isValid`` => ``Isvalid``)
* ``sonata.admin.label.strategy.underscore`` : Adds undescore to the label  - 
    ``isValid`` => ``form.label_is_valid``
* ``sonata.admin.label.strategy.noop`` : does not alter the string - ``isValid`` 
    => ``isValid``
* ``sonata.admin.label.strategy.bc`` : preserves the old label generation from 
    the early version of ``SonataAdminBundle``

``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 needs to be translated using generic keys the 
configuration can be switched to 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 translatable keys. It all depends on the 
    project's requirements.


.. note::

    When the strategy method is called, a context (form, filter, list, show) and
    a type (link, label, etc ...) arguments are passed.