Merge remote-tracking branch 'remotes/upstream/master'

Resources/doc/reference/translation.rst

@@ -3,24 +3,24 @@ 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
+* ``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
+* by over-riding the ``$translationDomain`` property
 
     .. code-block:: php
 
         <?php
         class PageAdmin extends Admin
         {
-            protected $translationDomain = 'SonataPageBundle';
+            protected $translationDomain = 'SonataPageBundle'; // default is 'messages'
         }
 
 
@@ -40,7 +40,7 @@ You have two options to configure the catalogue for the admin class:
             </service>
 
 
-An admin instance always gets the ``translator`` instance, so it can be used to
+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
@@ -55,7 +55,7 @@ translate messages within the ``configureFields`` method or in templates.
     {{ admin.trans('message_create_snapshots') }}
 
 
-The later solution is more flexible as no catalogue parameters are hardcoded.
+The last solution is most flexible, as no catalogue parameters are hardcoded, and is the recommended one to use.
 
 Translate field labels
 ----------------------
@@ -77,35 +77,34 @@ 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.
 
-The following example sets the translation domain on a form group:
+Setting the translation domain on an individual field:
 
 .. code-block:: php
 
-        $formMapper->with('form.my_group', array(
-            'translation_domain' => 'MyTranslationDomain'
-            ))
+        $formMapper->with('form.my_group')
             ->add('publishable', 'checkbox', array(), array(
-                // ...
                 'translation_domain' => 'MyTranslationDomain',
             ))
-            ->add('start_date', 'date', array(), array(
-            ));
+        ;
 
-Setting the translation domain on an individual field:
+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')
-            ->add('publishable', 'checkbox', array(), array(
-                // ...
-                'translation_domain' => 'MyTranslationDomain',
-            ));
+        $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 the field name. However a label can be defined as
-third argument of the ``add`` method:
+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
 
@@ -114,7 +113,11 @@ third argument of the ``add`` method:
     {
         public function configureFormFields(FormMapper $formMapper)
         {
-            $formMapper->add('isValid', null, array('required' => false, 'label' => 'label.is_valid'));
+            $formMapper->add(
+              'isValid', 
+              null, 
+              array('required' => false, 'label' => 'label.is_valid')
+            );
         }
     }
 
@@ -122,36 +125,35 @@ 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 ::
+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  -
+* ``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.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``.
+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 into
+The strategy can be quickly configured when the Admin class is registered in
 the Container:
 
 .. code-block:: xml