Skip to content

Commit 6ec443f

Browse files
wouterjwouterj
committed
Fixes after thorough reviews!
1 parent 2bd7f86 commit 6ec443f

File tree

2 files changed

+66
-64
lines changed

2 files changed

+66
-64
lines changed

‎translation/message_format.rst

+65-63
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
.. index::
22
single: Translation; Message Format
33

4-
How to translate messages using the ICU MessageFormat
4+
How to Translate Messages using the ICU MessageFormat
55
=====================================================
66

77
.. versionadded:: 4.2
88

99
Support for ICU MessageFormat was introduced in Symfony 4.2.
1010

1111
Messages (i.e. strings) in applications are almost never completely static.
12-
They contain variables or other complexer logic like pluralization. In order to
12+
They contain variables or other complex logic like pluralization. In order to
1313
handle this, the Translator component supports the `ICU MessageFormat`_ syntax.
1414

1515
Using the ICU Message Format
@@ -34,7 +34,7 @@ All messages in this file will now be processed by the
3434
Message Placeholders
3535
--------------------
3636

37-
The basic usage of the MessageFormat allows you to use placeholder (called
37+
The basic usage of the MessageFormat allows you to use placeholders (called
3838
*arguments* in ICU MessageFormat) in your messages:
3939

4040
.. configuration-block::
@@ -67,17 +67,19 @@ The basic usage of the MessageFormat allows you to use placeholder (called
6767
];
6868
6969
Everything within the curly braces (``{...}``) is processed by the formatter
70-
and replaced by it's placeholder::
70+
and replaced by its placeholder::
7171

72-
// ...
73-
echo $translator->trans('say_hello', ['name' => 'Fabien']); // Hello Fabien!
74-
echo $translator->trans('say_hello', ['name' => 'Symfony']); // Hello Symfony!
72+
// prints "Hello Fabien!"
73+
echo $translator->trans('say_hello', ['name' => 'Fabien']);
74+
75+
// prints "Hello Symfony!"
76+
echo $translator->trans('say_hello', ['name' => 'Symfony']);
7577

7678
Selecting Different Messages Based on a Condition
7779
-------------------------------------------------
7880

7981
The curly brace syntax allows to "modify" the output of the variable. One of
80-
these functions is the ``switch`` function. It acts like PHP's `switch statement`_
82+
these functions is the ``select`` function. It acts like PHP's `switch statement`_
8183
and allows to use different strings based on the value of the variable. A
8284
typical usage of this is gender:
8385

@@ -102,7 +104,7 @@ typical usage of this is gender:
102104
<body>
103105
<trans-unit id="invitation_title">
104106
<source>invitation_title</source>
105-
<target>{organizer_gender, select, female {{organizer_name} has invited you for her party!} male {{organizer_name} has invited you for his party!} other {{organizer_name} have invited you for their party!}}</target>
107+
<target>{organizer_gender, select, female {{organizer_name} has invited you for her party!} male {{organizer_name} has invited you for his party!} other {{organizer_name} have invited you for their party!}}</target>
106108
</trans-unit>
107109
</body>
108110
</file>
@@ -120,12 +122,11 @@ typical usage of this is gender:
120122
];
121123
122124
This might look very complex. The basic syntax for all functions is
123-
``{variable_name, function_name, function_statement}``. In this case, the
124-
function name is ``select`` and its statement contains the "cases" of this
125+
``{variable_name, function_name, function_statement}`` (where, as you see
126+
later, ``function_statement`` is optional for some functions). In this case,
127+
the function name is ``select`` and its statement contains the "cases" of this
125128
select. This function is applied over the ``organizer_gender`` variable::
126129

127-
// ...
128-
129130
// prints "Ryan has invited you for his party!"
130131
echo $translator->trans('invition_title', [
131132
'organizer_name' => 'Ryan',
@@ -154,23 +155,23 @@ you to use literal text in the select statements:
154155
in the switch statement, it is better to use "complex arguments" at the
155156
outermost structure of the message. The strings are in this way better
156157
readable for translators and, as you can see in the ``other`` case, other
157-
parts of the sentence mgith be influenced by the variable.
158+
parts of the sentence might be influenced by the variables.
158159

159160
Pluralization
160161
-------------
161162

162163
Another interesting function is ``plural``. It allows you to
163164
handle pluralization in your messages (e.g. ``There are 3 apples`` vs
164-
``There is one apple``). The function looks very similair to the ``select`` function:
165+
``There is one apple``). The function looks very similar to the ``select`` function:
165166

166167
.. configuration-block::
167168

168169
.. code-block:: yaml
169170
170171
# translations/messages.en.yaml
171-
nr_of_apples: >
172+
num_of_apples: >
172173
{apples, plural,
173-
=0 {There are no apples :(}
174+
=0 {There are no apples}
174175
one {There is one apple...}
175176
other {There are # apples!}
176177
}
@@ -182,9 +183,9 @@ handle pluralization in your messages (e.g. ``There are 3 apples`` vs
182183
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
183184
<file source-language="en" datatype="plaintext" original="file.ext">
184185
<body>
185-
<trans-unit id="nr_of_apples">
186-
<source>nr_of_apples</source>
187-
<target>{apples, plural, =0 {There are no apples :(} one {There is one apple...} other {There are # apples!}}</target>
186+
<trans-unit id="num_of_apples">
187+
<source>num_of_apples</source>
188+
<target>{apples, plural, =0 {There are no apples} one {There is one apple...} other {There are # apples!}}</target>
188189
</trans-unit>
189190
</body>
190191
</file>
@@ -194,43 +195,32 @@ handle pluralization in your messages (e.g. ``There are 3 apples`` vs
194195
195196
// translations/messages.en.php
196197
return [
197-
'nr_of_apples' => '{apples, plural,
198-
=0 {There are no apples :(}
198+
'num_of_apples' => '{apples, plural,
199+
=0 {There are no apples}
199200
one {There is one apple...}
200201
other {There are # apples!}
201202
}',
202203
];
203204
204205
Pluralization rules are actually quite complex and differ for each language.
205-
For instance, here is the mathematical representation of the Russian
206-
pluralization rules::
207-
208-
(($number % 10 == 1) && ($number % 100 != 11))
209-
? 0
210-
: ((($number % 10 >= 2)
211-
&& ($number % 10 <= 4)
212-
&& (($number % 100 < 10)
213-
|| ($number % 100 >= 20)))
214-
? 1
215-
: 2
216-
);
217-
218-
In order to facilitate this, the possible cases in the ``plural`` function are
219-
also different for each language. For instance, Russian has ``one``, ``few``,
220-
``many`` and ``other``, while English has only ``one`` and ``other``. The full
221-
list of possible cases can be found in Unicode's `Language Plural Rules`_
222-
document. By prefixing with ``=``, you can match exact values (like ``0`` in
223-
the above example).
206+
For instance, Russian uses different plural forms for numbers ending with 1;
207+
numbers ending with 2, 3 or 4; numbers ending with 5, 6, 7, 8 or 9; and even
208+
some exceptions of this!
224209

225-
Usage of this string is the same as with variables and select::
210+
In order to properly translate this, the possible cases in the ``plural``
211+
function are also different for each language. For instance, Russian has
212+
``one``, ``few``, ``many`` and ``other``, while English has only ``one`` and
213+
``other``. The full list of possible cases can be found in Unicode's
214+
`Language Plural Rules`_ document. By prefixing with ``=``, you can match exact
215+
values (like ``0`` in the above example).
226216

227-
// ...
217+
Usage of this string is the same as with variables and select::
228218

229219
// prints "There is one apple..."
230-
echo $translator->trans('nr_of_apples', ['apples' => 1]);
220+
echo $translator->trans('num_of_apples', ['apples' => 1]);
231221

232222
// prints "There are 23 apples!"
233-
echo $translator->trans('nr_of_apples', ['apples' => 23]);
223+
echo $translator->trans('num_of_apples', ['apples' => 23]);
234224

235225
.. note::
236226

@@ -269,15 +259,15 @@ Usage of this string is the same as with variables and select::
269259
}
270260
}
271261

272-
Other Placeholder Functions
273-
---------------------------
262+
Additional Placeholder Functions
263+
--------------------------------
274264

275-
Besides these, the MessageFormat comes with a couple other interesting functions.
265+
Besides these, the ICU MessageFormat comes with a couple other interesting functions.
276266

277267
Ordinal
278268
~~~~~~~
279269

280-
Similair to ``plural``, ``selectordinal`` allows you to use numbers as ordinal scale:
270+
Similar to ``plural``, ``selectordinal`` allows you to use numbers as ordinal scale:
281271

282272
.. configuration-block::
283273

@@ -286,12 +276,16 @@ Similair to ``plural``, ``selectordinal`` allows you to use numbers as ordinal s
286276
# translations/messages.en.yaml
287277
finish_place: >
288278
You finished {place, selectordinal,
289-
one {#st}
290-
two {#nd}
291-
few {#rd}
279+
one {#st}
280+
two {#nd}
281+
few {#rd}
292282
other {#th}
293283
}!
294284
285+
# when only formatting the number as ordinal (like above), you can also
286+
# use the `ordinal` function:
287+
finish_place: You finished {place, ordinal}!
288+
295289
.. code-block:: xml
296290
297291
<!-- translations/messages.en.xlf -->
@@ -301,7 +295,14 @@ Similair to ``plural``, ``selectordinal`` allows you to use numbers as ordinal s
301295
<body>
302296
<trans-unit id="finish_place">
303297
<source>finish_place</source>
304-
<target>{apples, plural, =0 {There are no apples :(} one {There is one apple...} other {There are # apples!}}</target>
298+
<target>You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!</target>
299+
</trans-unit>
300+
301+
<!-- when only formatting the number as ordinal (like
302+
above), you can also use the `ordinal` function: -->
303+
<trans-unit id="finish_place">
304+
<source>finish_place</source>
305+
<target>You finished {place, ordinal}!</target>
305306
</trans-unit>
306307
</body>
307308
</file>
@@ -317,12 +318,14 @@ Similair to ``plural``, ``selectordinal`` allows you to use numbers as ordinal s
317318
few {#rd}
318319
other {#th}
319320
}!',
321+
322+
// when only formatting the number as ordinal (like above), you can
323+
// also use the `ordinal` function:
324+
'finish_place' => 'You finished {place, ordinal}!',
320325
];
321326
322327
.. code-block:: php
323328
324-
// ...
325-
326329
// prints "You finished 1st!"
327330
echo $translator->trans('finish_place', ['place' => 1]);
328331
@@ -345,7 +348,7 @@ using the :phpclass:`IntlDateFormatter`:
345348
.. code-block:: yaml
346349
347350
# translations/messages.en.yaml
348-
published_at: 'Published at {time, date} - {time, time, short}'
351+
published_at: 'Published at {publication_date, date} - {publication_date, time, short}'
349352
350353
.. code-block:: xml
351354
@@ -356,7 +359,7 @@ using the :phpclass:`IntlDateFormatter`:
356359
<body>
357360
<trans-unit id="published_at">
358361
<source>published_at</source>
359-
<target>Published at {time, date} - {time, time, short}</target>
362+
<target>Published at {publication_date, date} - {publication_date, time, short}</target>
360363
</trans-unit>
361364
</body>
362365
</file>
@@ -366,15 +369,16 @@ using the :phpclass:`IntlDateFormatter`:
366369
367370
// translations/messages.en.php
368371
return [
369-
'published_at' => 'Published at {time, date} - {time, time, short}',
372+
'published_at' => 'Published at {publication_date, date} - {publication_date, time, short}',
370373
];
371374
372-
.. code-block:: php
375+
The "function statement" for the ``time`` and ``date`` functions can be one of
376+
short, medium, long or full, as documented on PHP.net.
373377

374-
// ...
378+
.. code-block:: php
375379
376380
// prints "Published at Jan 25, 2019 - 11:30 AM"
377-
echo $translator->trans('published_at', ['time' => new \DateTime('2019-01-25 11:30:00')]);
381+
echo $translator->trans('published_at', ['publication_date' => new \DateTime('2019-01-25 11:30:00')]);
378382
379383
Numbers
380384
~~~~~~~
@@ -419,8 +423,6 @@ The ``number`` formatter allows you to format numbers using Intl's :phpclass:`Nu
419423
420424
.. code-block:: php
421425
422-
// ...
423-
424426
// prints "82% of the work is done"
425427
echo $translator->trans('progress', ['progress' => 0.82]);
426428
// prints "100% of the work is done"

‎translation/templates.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ texts* and complex expressions:
103103

104104
.. code-block:: twig
105105
106-
{% trans_default_domain 'app' %}
106+
{% trans_default_domain 'app' %}
107107
108108
Note that this only influences the current template, not any "included"
109109
template (in order to avoid side effects).

0 commit comments

Comments
 (0)