123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187 |
- 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:
- * override the ``$translationDomain`` property
- .. code-block:: php
- <?php
- class PageAdmin extends AbstractAdmin
- {
- protected $translationDomain = 'SonataPageBundle'; // default is 'messages'
- }
- * inject the value through the container
- .. configuration-block::
- .. 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 #}
- {{ 'message_create_snapshots'|trans({}, 'SonataPageBundle') }}
- {# by using the admin trans with the configured catalogue #}
- {{ 'message_create_snapshots'|trans({}, admin.translationdomain) }}
- 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`, 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',
- ))
- ->end()
- ;
- 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())
- ->end()
- ;
- Translation can also be disabled on a specific field by setting
- ``translation_domain`` to ``false``.
- 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
- class PageAdmin extends AbstractAdmin
- {
- 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.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:
- .. configuration-block::
- .. code-block:: xml
- <service id="app.admin.project" class="AppBundle\Admin\ProjectAdmin">
- <tag
- name="sonata.admin"
- manager_type="orm"
- group="Project"
- label="Project"
- label_translator_strategy="sonata.admin.label.strategy.native"
- />
- <argument />
- <argument>AppBundle\Entity\Project</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, ``context`` (breadcrumb, datagrid, filter,
- form, list, show, etc.) and ``type`` (usually link or label) arguments are passed.
- For example, the call may look like: ``getLabel($label_key, 'breadcrumb', 'link')``
|