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
  across 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:

* by over-riding the ``$translationDomain`` property

    .. code-block:: php

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


* 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 ``configureFields`` method or in templates.

.. code-block:: jinja

    {# the classical call by using the twig trans helper #}
    {{ 'message_create_snapshots'|trans({}, 'SonataPageBundle') }}

    {# 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 last solution is most flexible, as no catalogue parameters are hardcoded, and is the recommended one to use.

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

The Admin bundle comes with a customized form field template. The most notable
change from the original one is the use of the translation domain provided by
either the Admin instance or the field description to translate labels.

Overriding the translation domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The translation domain (message catalog) can be overridden at either the form
group or individual field level.

If a translation domain is set at the group level it will cascade down to all
fields within the group.

Overriding the translation domain is of particular use when using
:doc:`extensions <extensions>`, where the extension and the translations would
be defined in one bundle, but implemented in many different Admin instances.

Setting the translation domain on an individual field:

.. code-block:: php

        $formMapper->with('form.my_group')
            ->add('publishable', 'checkbox', array(), array(
                'translation_domain' => 'MyTranslationDomain',
            ))
        ;

The following example sets the default translation domain on a form group and 
over-rides that setting for one of the fields:

.. code-block:: php

        $formMapper
            ->with('form.my_group', array('translation_domain' => 'MyDomain'))
                ->add('publishable', 'checkbox', array(), array(
                    'translation_domain' => 'AnotherDomain',
                ))
                ->add('start_date', 'date', array(), array())
        ;

Setting the label name
^^^^^^^^^^^^^^^^^^^^^^

By default, the label is set to a sanitized version of the field name. A custom
label can be defined as 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')
            );
        }
    }

Label strategies
^^^^^^^^^^^^^^^^

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

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

* ``sonata.admin.label.strategy.native``: DEFAULT - Makes the string human 
  readable
    ``isValid`` => ``Is Valid``
* ``sonata.admin.label.strategy.form_component``: The default behavior from the Form 
  Component
    ``isValid`` => ``Isvalid``
* ``sonata.admin.label.strategy.underscore``: Changes the name into a token suitable for 
  translation by prepending "form.label" to an underscored version of the field name
    ``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 (single) language
apps based on the field name. It is reasonable to start with the ``native`` strategy
and then, when the application needs to be translated using generic keys, the
configuration can be switched to ``underscore``.

The strategy can be quickly configured when the Admin class is registered in
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.