Skip to content

Commit fdc886a

Browse files
javiereguiluzjaviereguiluz
committed
minor #10065 [Form] New translation_parameters option (webnet-fr, Vladyslav Riabchenko)
This PR was merged into the master branch. Discussion ---------- [Form] New translation_parameters option Documenting symfony/symfony#28635 Commits ------- 20c6f5a correct arrays short syntax 70f36ad correct bug d7e7b0b correct attr link in entity type doc 71fc7ce typo in form_translation_parameters docs a655106 confirm with 28635 32e79e1 correct link error c57d30a new translation_parameters form option
2 parents a91d0b9 + 20c6f5a commit fdc886a

11 files changed

+504
-2
lines changed

‎reference/forms/types/button.rst

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ A simple, non-responsive button.
1313
| options | - `disabled`_ |
1414
| | - `label`_ |
1515
| | - `translation_domain`_ |
16+
| | - `label_translation_parameters`_ |
17+
| | - `attr_translation_parameters`_ |
1618
+----------------------+----------------------------------------------------------------------+
1719
| Parent type | none |
1820
+----------------------+----------------------------------------------------------------------+
@@ -51,3 +53,83 @@ as a key. This can be useful when you need to set a custom class for the button:
5153
.. include:: /reference/forms/types/options/button_label.rst.inc
5254

5355
.. include:: /reference/forms/types/options/button_translation_domain.rst.inc
56+
57+
label_translation_parameters
58+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59+
60+
**type**: ``array`` **default**: ``[]``
61+
62+
Translated `label`_ can contain
63+
:ref:`placeholders <component-translation-placeholders>`.
64+
This option allows you to pass an array of parameters in order to replace
65+
placeholders with actual values.
66+
67+
Given this translation message:
68+
69+
.. code-block:: yaml
70+
71+
# translations/messages.en.yml
72+
form.order.submit_to_company: Send an order to %company%
73+
74+
you can specify placeholder value:
75+
76+
.. code-block:: php
77+
78+
use Symfony\Component\Form\Extension\Core\Type\ButtonType;
79+
// ...
80+
81+
$builder->add('send', ButtonType::class, array(
82+
'label' => 'form.order.submit_to_company',
83+
'label_translation_parameters' => array(
84+
'%company%' => 'ACME Inc.',
85+
),
86+
));
87+
88+
Note that ``label_translation_parameters`` of buttons are merged with those of its
89+
parent. In other words the parent's translation parameters are available for
90+
children's buttons but can be overriden:
91+
92+
.. code-block:: php
93+
94+
// App/Controller/OrderController.php
95+
use App\Form\OrderType;
96+
// ...
97+
98+
$form = $this->createForm(OrderType::class, $order, array(
99+
// available to all children, grandchildren and so on.
100+
'label_translation_parameters' => array(
101+
'%company%' => 'ACME',
102+
),
103+
));
104+
105+
.. code-block:: php
106+
107+
// App/Form/OrderType.php
108+
use Symfony\Component\Form\Extension\Core\Type\ButtonType;
109+
// ...
110+
111+
$builder->add('send', ButtonType::class, array(
112+
'label' => 'form.order.submit_to_company',
113+
// Value of parent's 'label_translation_parameters' will be merged with
114+
// this field's empty 'label_translation_parameters'.
115+
// array('%company%' => 'ACME') will be used to translate this label.
116+
));
117+
118+
.. code-block:: php
119+
120+
// App/Form/OrderType.php
121+
use Symfony\Component\Form\Extension\Core\Type\ButtonType;
122+
// ...
123+
124+
$builder->add('send', ButtonType::class, array(
125+
'label' => 'form.order.submit_to_company',
126+
'label_translation_parameters' => array(
127+
'%company%' => 'American Company Making Everything',
128+
),
129+
// Value of parent's 'label_translation_parameters' will be merged with
130+
// this button's 'label_translation_parameters'.
131+
// array('%company%' => 'American Company Making Everything')
132+
// will be used to translate this label.
133+
));
134+
135+
.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc

‎reference/forms/types/choice.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
4545
| | - `mapped`_ |
4646
| | - `required`_ |
4747
| | - `translation_domain`_ |
48+
| | - `label_translation_parameters`_ |
49+
| | - `attr_translation_parameters`_ |
50+
| | - `help_translation_parameters`_ |
4851
+-------------+------------------------------------------------------------------------------+
4952
| Parent type | :doc:`FormType </reference/forms/types/form>` |
5053
+-------------+------------------------------------------------------------------------------+
@@ -297,6 +300,12 @@ These options inherit from the :doc:`FormType </reference/forms/types/form>`:
297300

298301
.. include:: /reference/forms/types/options/choice_type_translation_domain.rst.inc
299302

303+
.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
304+
305+
.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
306+
307+
.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc
308+
300309
Field Variables
301310
---------------
302311

‎reference/forms/types/entity.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ objects from the database.
3636
| | |
3737
| | from the :doc:`FormType </reference/forms/types/form>`: |
3838
| | |
39+
| | - `attr`_ |
3940
| | - `data`_ |
4041
| | - `disabled`_ |
4142
| | - `empty_data`_ |
@@ -49,6 +50,9 @@ objects from the database.
4950
| | - `label_format`_ |
5051
| | - `mapped`_ |
5152
| | - `required`_ |
53+
| | - `label_translation_parameters`_ |
54+
| | - `attr_translation_parameters`_ |
55+
| | - `help_translation_parameters`_ |
5256
+-------------+------------------------------------------------------------------+
5357
| Parent type | :doc:`ChoiceType </reference/forms/types/choice>` |
5458
+-------------+------------------------------------------------------------------+
@@ -312,6 +316,8 @@ when rendering the field:
312316
These options inherit from the :doc:`form </reference/forms/types/form>`
313317
type:
314318

319+
.. include:: /reference/forms/types/options/attr.rst.inc
320+
315321
.. include:: /reference/forms/types/options/data.rst.inc
316322

317323
.. include:: /reference/forms/types/options/disabled.rst.inc
@@ -347,3 +353,9 @@ The actual default value of this option depends on other field options:
347353
.. include:: /reference/forms/types/options/mapped.rst.inc
348354

349355
.. include:: /reference/forms/types/options/required.rst.inc
356+
357+
.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
358+
359+
.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc
360+
361+
.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc

‎reference/forms/types/form.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ on all types for which ``FormType`` is the parent.
2222
| | - `help`_ |
2323
| | - `help_attr`_ |
2424
| | - `help_html`_ |
25+
| | - `help_translation_parameters`_ |
2526
| | - `inherit_data`_ |
2627
| | - `invalid_message`_ |
2728
| | - `invalid_message_parameters`_ |
@@ -42,6 +43,8 @@ on all types for which ``FormType`` is the parent.
4243
| | - `disabled`_ |
4344
| | - `label`_ |
4445
| | - `translation_domain`_ |
46+
| | - `label_translation_parameters`_ |
47+
| | - `attr_translation_parameters`_ |
4548
+-----------+--------------------------------------------------------------------+
4649
| Parent | none |
4750
+-----------+--------------------------------------------------------------------+
@@ -113,6 +116,8 @@ The actual default value of this option depends on other field options:
113116

114117
.. include:: /reference/forms/types/options/help_html.rst.inc
115118

119+
.. include:: /reference/forms/types/options/help_translation_parameters.rst.inc
120+
116121
.. include:: /reference/forms/types/options/inherit_data.rst.inc
117122

118123
.. 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).
167172
.. include:: /reference/forms/types/options/label.rst.inc
168173

169174
.. include:: /reference/forms/types/options/translation_domain.rst.inc
175+
176+
.. include:: /reference/forms/types/options/label_translation_parameters.rst.inc
177+
178+
.. include:: /reference/forms/types/options/attr_translation_parameters.rst.inc

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
attr_translation_parameters
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
**type**: ``array`` **default**: ``[]``
5+
6+
Some translated `attr`_ (``title`` and ``placeholder``) can
7+
contain :ref:`placeholders <component-translation-placeholders>`.
8+
This option allows you to pass an array of parameters in order to replace
9+
placeholders with actual values.
10+
11+
Given this translation message:
12+
13+
.. code-block:: yaml
14+
15+
# translations/messages.en.yml
16+
form.order.id.placeholder: Enter unique identifier of the order to %company%
17+
form.order.id.title: This will be the reference in communications with %company%
18+
19+
you can specify placeholder value:
20+
21+
.. code-block:: php
22+
23+
$builder->add('id', null, array(
24+
'attr' => array(
25+
'placeholder' => 'form.order.id.placeholder',
26+
'title' => 'form.order.id.title',
27+
),
28+
'attr_translation_parameters' => [
29+
'%company%' => 'ACME Inc.'
30+
]
31+
));
32+
33+
Note that ``attr_translation_parameters`` of children fields are merged with those
34+
of its parent. In other words the parent's translation parameters are available
35+
for children but can be overriden:
36+
37+
.. code-block:: php
38+
39+
// App/Controller/OrderController.php
40+
use App\Form\OrderType;
41+
// ...
42+
43+
$form = $this->createForm(OrderType::class, $order, array(
44+
// available to all children, grandchildren and so on.
45+
'attr_translation_parameters' => array(
46+
'%company%' => 'ACME',
47+
),
48+
));
49+
50+
.. code-block:: php
51+
52+
// App/Form/OrderType.php
53+
// ...
54+
55+
$builder->add('id', null, array(
56+
'attr' => array(
57+
'placeholder' => 'form.order.id.placeholder',
58+
'title' => 'form.order.id.title',
59+
),
60+
// Value of parent's 'attr_translation_parameters' will be merged with
61+
// this field's empty 'attr_translation_parameters'.
62+
// array('%company%' => 'ACME') will be used to translate 'placeholder' and 'title'.
63+
));
64+
65+
.. code-block:: php
66+
67+
// App/Form/OrderType.php
68+
// ...
69+
70+
$builder->add('id', null, array(
71+
'attr' => array(
72+
'placeholder' => 'form.order.id.placeholder',
73+
'title' => 'form.order.id.title',
74+
),
75+
'attr_translation_parameters' => array(
76+
'%company%' => 'American Company Making Everything',
77+
),
78+
// Value of parent's 'attr_translation_parameters' will be merged with
79+
// this field's 'attr_translation_parameters'.
80+
// array('%company%' => 'American Company Making Everything')
81+
// will be used to translate 'placeholder' and 'title'.
82+
));

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ translation_domain
55

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

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

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
help_translation_parameters
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
**type**: ``array`` **default**: ``[]``
5+
6+
Translated `help`_ can
7+
contain :ref:`placeholders <component-translation-placeholders>`.
8+
This option allows you to pass an array of parameters in order to replace
9+
placeholders with actual values.
10+
11+
Given this translation message:
12+
13+
.. code-block:: yaml
14+
15+
# translations/messages.en.yml
16+
form.order.id.help: This will be the reference in communications with %company%
17+
18+
you can specify placeholder value:
19+
20+
.. code-block:: php
21+
22+
$builder->add('id', null, array(
23+
'help' => 'form.order.id.help',
24+
'help_translation_parameters' => [
25+
'%company%' => 'ACME Inc.'
26+
]
27+
));
28+
29+
Note that ``help_translation_parameters`` of children fields are merged with those
30+
of its parent. In other words the parent's translation parameters are available
31+
for children but can be overriden:
32+
33+
.. code-block:: php
34+
35+
// App/Controller/OrderController.php
36+
use App\Form\OrderType;
37+
// ...
38+
39+
$form = $this->createForm(OrderType::class, $order, array(
40+
// available to all children, grandchildren and so on.
41+
'help_translation_parameters' => array(
42+
'%company%' => 'ACME',
43+
),
44+
));
45+
46+
.. code-block:: php
47+
48+
// App/Form/OrderType.php
49+
// ...
50+
51+
$builder->add('id', null, array(
52+
'help' => 'form.order.id.help',
53+
// Value of parent's 'help_translation_parameters' will be merged with
54+
// this field's empty 'help_translation_parameters'.
55+
// array('%company%' => 'ACME') will be used to translate 'help'.
56+
));
57+
58+
.. code-block:: php
59+
60+
// App/Form/OrderType.php
61+
// ...
62+
63+
$builder->add('id', null, array(
64+
'help' => 'form.order.id.help',
65+
'help_translation_parameters' => array(
66+
'%company%' => 'American Company Making Everything',
67+
),
68+
// Value of parent's 'help_translation_parameters' will be merged with
69+
// this field's 'help_translation_parameters'.
70+
// array('%company%' => 'American Company Making Everything')
71+
// will be used to translate 'help'.
72+
));

0 commit comments

Comments
 (0)