translation.rst 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. Translation
  2. ===========
  3. There are two main catalogue names in an Admin class:
  4. * ``SonataAdminBundle``: this catalogue is used to translate shared messages
  5. across different Admins
  6. * ``messages``: this catalogue is used to translate the messages for the current
  7. Admin
  8. Ideally the ``messages`` catalogue should be changed to avoid any issues with
  9. other Admin classes.
  10. You have two options to configure the catalogue for the Admin class:
  11. * override the ``$translationDomain`` property
  12. .. code-block:: php
  13. <?php
  14. class PageAdmin extends AbstractAdmin
  15. {
  16. protected $translationDomain = 'SonataPageBundle'; // default is 'messages'
  17. }
  18. * inject the value through the container
  19. .. configuration-block::
  20. .. code-block:: xml
  21. <service id="sonata.page.admin.page" class="Sonata\PageBundle\Admin\PageAdmin">
  22. <tag name="sonata.admin" manager_type="orm" group="sonata_page" label="Page" />
  23. <argument />
  24. <argument>Application\Sonata\PageBundle\Entity\Page</argument>
  25. <argument />
  26. <call method="setTranslationDomain">
  27. <argument>SonataPageBundle</argument>
  28. </call>
  29. </service>
  30. An Admin instance always gets the ``translator`` instance, so it can be used to
  31. translate messages within the ``configureFields`` method or in templates.
  32. .. code-block:: jinja
  33. {# the classical call by using the twig trans helper #}
  34. {{ 'message_create_snapshots'|trans({}, 'SonataPageBundle') }}
  35. {# by using the admin trans method with hardcoded catalogue #}
  36. {{ 'message_create_snapshots'|trans({}, 'SonataPageBundle') }}
  37. {# by using the admin trans with the configured catalogue #}
  38. {{ 'message_create_snapshots'|trans({}, admin.translationdomain) }}
  39. The last solution is most flexible, as no catalogue parameters are hardcoded, and is the recommended one to use.
  40. Translate field labels
  41. ----------------------
  42. The Admin bundle comes with a customized form field template. The most notable
  43. change from the original one is the use of the translation domain provided by
  44. either the Admin instance or the field description to translate labels.
  45. Overriding the translation domain
  46. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  47. The translation domain (message catalog) can be overridden at either the form
  48. group or individual field level.
  49. If a translation domain is set at the group level it will cascade down to all
  50. fields within the group.
  51. Overriding the translation domain is of particular use when using
  52. :doc:`extensions`, where the extension and the translations would
  53. be defined in one bundle, but implemented in many different Admin instances.
  54. Setting the translation domain on an individual field:
  55. .. code-block:: php
  56. $formMapper
  57. ->with('form.my_group')
  58. ->add('publishable', 'checkbox', array(), array(
  59. 'translation_domain' => 'MyTranslationDomain',
  60. ))
  61. ->end()
  62. ;
  63. The following example sets the default translation domain on a form group and
  64. over-rides that setting for one of the fields:
  65. .. code-block:: php
  66. $formMapper
  67. ->with('form.my_group', array('translation_domain' => 'MyDomain'))
  68. ->add('publishable', 'checkbox', array(), array(
  69. 'translation_domain' => 'AnotherDomain',
  70. ))
  71. ->add('start_date', 'date', array(), array())
  72. ->end()
  73. ;
  74. Translation can also be disabled on a specific field by setting
  75. ``translation_domain`` to ``false``.
  76. Setting the label name
  77. ^^^^^^^^^^^^^^^^^^^^^^
  78. By default, the label is set to a sanitized version of the field name. A custom
  79. label can be defined as the third argument of the ``add`` method:
  80. .. code-block:: php
  81. class PageAdmin extends AbstractAdmin
  82. {
  83. public function configureFormFields(FormMapper $formMapper)
  84. {
  85. $formMapper
  86. ->add('isValid', null, array(
  87. 'required' => false,
  88. 'label' => 'label.is_valid',
  89. ))
  90. ;
  91. }
  92. }
  93. Label strategies
  94. ^^^^^^^^^^^^^^^^
  95. There is another option for rapid prototyping or to avoid spending too much time
  96. adding the ``label`` key to all option fields: **Label Strategies**. By default
  97. labels are generated by using a simple rule:
  98. ``isValid => Is Valid``
  99. The ``AdminBundle`` comes with different key label generation strategies:
  100. * ``sonata.admin.label.strategy.native``: DEFAULT - Makes the string human readable
  101. ``isValid`` => ``Is Valid``
  102. * ``sonata.admin.label.strategy.form_component``: The default behavior from the Form Component
  103. ``isValid`` => ``Isvalid``
  104. * ``sonata.admin.label.strategy.underscore``: Changes the name into a token suitable
  105. for translation by prepending "form.label" to an underscored version of the field name
  106. ``isValid`` => ``form.label_is_valid``
  107. * ``sonata.admin.label.strategy.noop``: does not alter the string
  108. ``isValid`` => ``isValid``
  109. ``sonata.admin.label.strategy.underscore`` will be better for i18n applications
  110. and ``sonata.admin.label.strategy.native`` will be better for native (single) language
  111. apps based on the field name. It is reasonable to start with the ``native`` strategy
  112. and then, when the application needs to be translated using generic keys, the
  113. configuration can be switched to ``underscore``.
  114. The strategy can be quickly configured when the Admin class is registered in
  115. the Container:
  116. .. configuration-block::
  117. .. code-block:: xml
  118. <service id="app.admin.project" class="AppBundle\Admin\ProjectAdmin">
  119. <tag
  120. name="sonata.admin"
  121. manager_type="orm"
  122. group="Project"
  123. label="Project"
  124. label_translator_strategy="sonata.admin.label.strategy.native"
  125. />
  126. <argument />
  127. <argument>AppBundle\Entity\Project</argument>
  128. <argument />
  129. </service>
  130. .. note::
  131. In all cases the label will be used by the ``Translator``. The strategy is
  132. just a quick way to generate translatable keys. It all depends on the
  133. project's requirements.
  134. .. note::
  135. When the strategy method is called, ``context`` (breadcrumb, datagrid, filter,
  136. form, list, show, etc.) and ``type`` (usually link or label) arguments are passed.
  137. For example, the call may look like: ``getLabel($label_key, 'breadcrumb', 'link')``