minor symfony#7205 Simplified the use of transChoice() (javiereguiluz)

xabbuh · xabbuh · commit 65d2f99d0f48 · 2017-05-17T09:13:42.000+02:00
This PR was squashed before being merged into the 3.2 branch (closes symfony#7205). Discussion ---------- Simplified the use of transChoice() This fixes symfony#7172. I'm not happy with the result, so I'm open to comments to improve this. Thanks! Commits ------- 1e4e9a7 Simplified the use of transChoice()
diff --git a/components/translation/usage.rst b/components/translation/usage.rst
@@ -253,16 +253,39 @@ all the forms as a string separated by a pipe (``|``)::
 To translate pluralized messages, use the
 :method:`Symfony\\Component\\Translation\\Translator::transChoice` method::
 
+    // the %count% placeholder is assigned to the second argument...
     $translator->transChoice(
         'There is one apple|There are %count% apples',
+        10
+    );
+
+    // ...but you can define more placeholders if needed
+    $translator->transChoice(
+        'Hurry up %name%! There is one apple left.|There are %count% apples left.',
         10,
-        array('%count%' => 10)
+        // no need to include %count% here; Symfony does that for you
+        array('%name%' => $user->getName())
     );
 
 The second argument (``10`` in this example) is the *number* of objects being
 described and is used to determine which translation to use and also to populate
 the ``%count%`` placeholder.
 
+.. versionadded:: 3.2
+
+    Before Symfony 3.2, the placeholder used to select the plural (``%count%``
+    in this example) must be included in the third optional argument of the
+    ``transChoice()`` method::
+
+        $translator->transChoice(
+            'There is one apple|There are %count% apples',
+            10,
+            array('%count%' => 10)
+        );
+
+    Starting from Symfony 3.2, when the only placeholder is ``%count%``, you
+    don't have to pass this third argument.
+
 Based on the given number, the translator chooses the right plural form.
 In English, most words have a singular form when there is exactly one object
 and a plural form for all other numbers (0, 2, 3...). So, if ``count`` is
@@ -366,11 +389,25 @@ use for translation::
     $translator->transChoice(
         '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
         10,
-        array('%count%' => 10),
+        array(),
         'messages',
         'fr_FR'
     );
 
+.. note::
+
+    Starting from Symfony 3.2, the third argument of ``transChoice()`` is
+    optional when the only placeholder in use is ``%count%``. In previous
+    Symfony versions you needed to define it always::
+
+        $translator->transChoice(
+            '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
+            10,
+            array('%count%' => 10),
+            'messages',
+            'fr_FR'
+        );
+
 Retrieving the Message Catalogue
 --------------------------------
 
