[Form] New translation_parameters option

reference/forms/types/button.rst

@@ -13,6 +13,8 @@ A simple, non-responsive button.
 | options              | - `disabled`_                                                        |
 |                      | - `label`_                                                           |
 |                      | - `translation_domain`_                                              |
+|                      | - `label_translation_parameters`_                                    |
+|                      | - `attr_translation_parameters`_                                     |
 +----------------------+----------------------------------------------------------------------+
 | Parent type          | none                                                                 |
 +----------------------+----------------------------------------------------------------------+
@@ -51,3 +53,83 @@ as a key. This can be useful when you need to set a custom class for the button:
 .. include:: /reference/forms/types/options/button_label.rst.inc
 
 .. include:: /reference/forms/types/options/button_translation_domain.rst.inc
+
+label_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``array()``
+
+Translated `label`_ can contain
+:ref:`placeholders <component-translation-placeholders>`.
+This option allows you to pass an array of parameters in order to replace
+placeholders with actual values.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yml
+    form.order.submit_to_company: Send an order to %company%
+
+you can specify placeholder value:
+
+.. code-block:: php
+
+    use Symfony\Component\Form\Extension\Core\Type\ButtonType;
+    // ...
+
+    $builder->add('send', ButtonType::class, array(
+        'label' => 'form.order.submit_to_company',
+        'label_translation_parameters' => array(
+            '%company%' => 'ACME Inc.',
+        ),
+    ));
+
+Note that `label_translation_parameters` of buttons are merged with those of its
+parent. In other words the parent's translation parameters are available for
+children's buttons but can be overriden:
+
+.. code-block:: php
+
+    // App/Controller/OrderController.php
+    use App\Form\OrderType;
+    // ...
+
+    $form = $this->createForm(OrderType::class, $order, array(
+        // available to all children, grandchildren and so on.
+        'label_translation_parameters' => array(
+            '%company%' => 'ACME',
+        ),
+    ));
+
+.. code-block:: php
+
+    // App/Form/OrderType.php
+    use Symfony\Component\Form\Extension\Core\Type\ButtonType;
+    // ...
+
+    $builder->add('send', ButtonType::class, array(
+        'label' => 'form.order.submit_to_company',
+        // Value of parent's 'label_translation_parameters' will be merged with
+        // this field's empty 'label_translation_parameters'.
+        // array('%company%' => 'ACME') will be used to translate this label.
+    ));
+
+.. code-block:: php
+
+    // App/Form/OrderType.php
+    use Symfony\Component\Form\Extension\Core\Type\ButtonType;
+    // ...
+
+    $builder->add('send', ButtonType::class, array(
+        'label' => 'form.order.submit_to_company',
+        'label_translation_parameters' => array(
+            '%company%' => 'American Company Making Everything',
+        ),
+        // Value of parent's 'label_translation_parameters' will be merged with
+        // this button's 'label_translation_parameters'.
+        // array('%company%' => 'American Company Making Everything')
+        // will be used to translate this label.
+    ));
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc

reference/forms/types/choice.rst

@@ -45,6 +45,9 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
 |             | - `mapped`_                                                                  |
 |             | - `required`_                                                                |
 |             | - `translation_domain`_                                                      |
+|             | - `label_translation_parameters`_                                            |
+|             | - `attr_translation_parameters`_                                             |
+|             | - `help_translation_parameters`_                                             |
 +-------------+------------------------------------------------------------------------------+
 | Parent type | :doc:`FormType </reference/forms/types/form>`                                |
 +-------------+------------------------------------------------------------------------------+
@@ -297,6 +300,12 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
 
 .. include:: /reference/forms/types/options/choice_type_translation_domain.rst.inc
 
+.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc
+
 Field Variables
 ---------------
 

reference/forms/types/entity.rst

@@ -36,6 +36,7 @@ objects from the database.
 |             |                                                                  |
 |             | from the :doc:`FormType </reference/forms/types/form>`:          |
 |             |                                                                  |
+|             | - `attr`_                                                        |
 |             | - `data`_                                                        |
 |             | - `disabled`_                                                    |
 |             | - `empty_data`_                                                  |
@@ -49,6 +50,9 @@ objects from the database.
 |             | - `label_format`_                                                |
 |             | - `mapped`_                                                      |
 |             | - `required`_                                                    |
+|             | - `label_translation_parameters`_                                |
+|             | - `attr_translation_parameters`_                                 |
+|             | - `help_translation_parameters`_                                 |
 +-------------+------------------------------------------------------------------+
 | Parent type | :doc:`ChoiceType </reference/forms/types/choice>`                |
 +-------------+------------------------------------------------------------------+
@@ -312,6 +316,8 @@ when rendering the field:
 These options inherit from the :doc:`form </reference/forms/types/form>`
 type:
 
+.. include:: /reference/forms/types/options/attr.rst.inc
+
 .. include:: /reference/forms/types/options/data.rst.inc
 
 .. include:: /reference/forms/types/options/disabled.rst.inc
@@ -347,3 +353,9 @@ The actual default value of this option depends on other field options:
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
 .. include:: /reference/forms/types/options/required.rst.inc
+
+.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc

reference/forms/types/form.rst

@@ -22,6 +22,7 @@ on all types for which ``FormType`` is the parent.
 |           | - `help`_                                                          |
 |           | - `help_attr`_                                                     |
 |           | - `help_html`_                                                     |
+|           | - `help_translation_parameters`_                                   |
 |           | - `inherit_data`_                                                  |
 |           | - `invalid_message`_                                               |
 |           | - `invalid_message_parameters`_                                    |
@@ -42,6 +43,8 @@ on all types for which ``FormType`` is the parent.
 |           | - `disabled`_                                                      |
 |           | - `label`_                                                         |
 |           | - `translation_domain`_                                            |
+|           | - `label_translation_parameters`_                                  |
+|           | - `attr_translation_parameters`_                                   |
 +-----------+--------------------------------------------------------------------+
 | Parent    | none                                                               |
 +-----------+--------------------------------------------------------------------+
@@ -113,6 +116,8 @@ The actual default value of this option depends on other field options:
 
 .. include:: /reference/forms/types/options/help_html.rst.inc
 
+.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc
+
 .. include:: /reference/forms/types/options/inherit_data.rst.inc
 
 .. include:: /reference/forms/types/options/invalid_message.rst.inc
@@ -167,3 +172,7 @@ of the form type tree (i.e. it cannot be used as a form type on its own).
 .. include:: /reference/forms/types/options/label.rst.inc
 
 .. include:: /reference/forms/types/options/translation_domain.rst.inc
+
+.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
+
+.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc

reference/forms/types/options/attr_translation_parameters.rst.inc

@@ -0,0 +1,82 @@
+attr_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``array()``
+
+Some translated `attr`_ (``title`` and ``placeholder``) can
+contain :ref:`placeholders <component-translation-placeholders>`.
+This option allows you to pass an array of parameters in order to replace
+placeholders with actual values.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yml
+    form.order.id.placeholder: Enter unique identifier of the order to %company%
+    form.order.id.title: This will be the reference in communications with %company%
+
+you can specify placeholder value:
+
+.. code-block:: php
+
+    $builder->add('id', null, array(
+        'attr' => array(
+            'placeholder' => 'form.order.id.placeholder',
+            'title' => 'form.order.id.title',
+        ),
+        'attr_translation_parameters' => [
+            '%company%' => 'ACME Inc.'
+        ]
+    ));
+
+Note that `attr_translation_parameters` of children fields are merged with those
+of its parent. In other words the parent's translation parameters are available
+for children but can be overriden:
+
+.. code-block:: php
+
+    // App/Controller/OrderController.php
+    use App\Form\OrderType;
+    // ...
+
+    $form = $this->createForm(OrderType::class, $order, array(
+        // available to all children, grandchildren and so on.
+        'attr_translation_parameters' => array(
+            '%company%' => 'ACME',
+        ),
+    ));
+
+    .. code-block:: php
+
+    // App/Form/OrderType.php
+    // ...
+
+    $builder->add('id', null, array(
+        'attr' => array(
+            'placeholder' => 'form.order.id.placeholder',
+            'title' => 'form.order.id.title',
+        ),
+        // Value of parent's 'attr_translation_parameters' will be merged with
+        // this field's empty 'attr_translation_parameters'.
+        // array('%company%' => 'ACME') will be used to translate 'placeholder' and 'title'.
+    ));
+
+    .. code-block:: php
+
+    // App/Form/OrderType.php
+    // ...
+
+    $builder->add('id', null, array(
+        'attr' => array(
+            'placeholder' => 'form.order.id.placeholder',
+            'title' => 'form.order.id.title',
+        ),
+        'attr_translation_parameters' => array(
+            '%company%' => 'American Company Making Everything',
+        ),
+        // Value of parent's 'attr_translation_parameters' will be merged with
+        // this field's 'attr_translation_parameters'.
+        // array('%company%' => 'American Company Making Everything')
+        // will be used to translate 'placeholder' and 'title'.
+    ));

reference/forms/types/options/choice_type_translation_domain.rst.inc

@@ -5,4 +5,4 @@ translation_domain
 
 In case `choice_translation_domain`_ is set to ``true`` or ``null``, this
 configures the exact translation domain that will be used for any labels or
-options that are rendered for this field
+options that are rendered for this field.

reference/forms/types/options/help_translation_parameters.rst.inc

@@ -0,0 +1,72 @@
+help_translation_parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``array()``
+
+Translated `help`_ can
+contain :ref:`placeholders <component-translation-placeholders>`.
+This option allows you to pass an array of parameters in order to replace
+placeholders with actual values.
+
+Given this translation message:
+
+.. code-block:: yaml
+
+    # translations/messages.en.yml
+    form.order.id.help: This will be the reference in communications with %company%
+
+you can specify placeholder value:
+
+.. code-block:: php
+
+    $builder->add('id', null, array(
+        'help' => 'form.order.id.help',
+        'help_translation_parameters' => [
+            '%company%' => 'ACME Inc.'
+        ]
+    ));
+
+Note that `help_translation_parameters` of children fields are merged with those
+of its parent. In other words the parent's translation parameters are available
+for children but can be overriden:
+
+.. code-block:: php
+
+    // App/Controller/OrderController.php
+    use App\Form\OrderType;
+    // ...
+
+    $form = $this->createForm(OrderType::class, $order, array(
+        // available to all children, grandchildren and so on.
+        'help_translation_parameters' => array(
+            '%company%' => 'ACME',
+        ),
+    ));
+
+    .. code-block:: php
+
+    // App/Form/OrderType.php
+    // ...
+
+    $builder->add('id', null, array(
+        'help' => 'form.order.id.help',
+        // Value of parent's 'help_translation_parameters' will be merged with
+        // this field's empty 'help_translation_parameters'.
+        // array('%company%' => 'ACME') will be used to translate 'help'.
+    ));
+
+    .. code-block:: php
+
+    // App/Form/OrderType.php
+    // ...
+
+    $builder->add('id', null, array(
+        'help' => 'form.order.id.help',
+        'help_translation_parameters' => array(
+            '%company%' => 'American Company Making Everything',
+        ),
+        // Value of parent's 'help_translation_parameters' will be merged with
+        // this field's 'help_translation_parameters'.
+        // array('%company%' => 'American Company Making Everything')
+        // will be used to translate 'help'.
+    ));