feature #4834 [translator] use the new fallbacks option. (aitboudad)

This PR was merged into the 2.3 branch.

Discussion
----------

[translator] use the new fallbacks option.

| Q             | A
| ------------- | ---
| Doc fix?        | yes
| New docs?   | no
| Applies to     | all
| Fixed tickets | symfony/symfony#13376

Commits
-------

92194f2 [config][translator] use the new fallbacks option.

Author: weaverryan

best_practices/i18n.rst

@@ -11,7 +11,7 @@ following ``translator`` configuration option and set your application locale:
     # app/config/config.yml
     framework:
         # ...
-        translator: { fallback: "%locale%" }
+        translator: { fallbacks: ["%locale%"] }
 
     # app/config/parameters.yml
     parameters:

book/translation.rst

@@ -59,7 +59,7 @@ enable the ``translator`` in your configuration:
 
         # app/config/config.yml
         framework:
-            translator: { fallback: en }
+            translator: { fallbacks: [en] }
 
     .. code-block:: xml
 
@@ -74,18 +74,20 @@ enable the ``translator`` in your configuration:
                 http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
             <framework:config>
-                <framework:translator fallback="en" />
+                <framework:translator>
+                    <framework:fallback>en</framework:fallback>
+                </framework:translator>
             </framework:config>
         </container>
 
     .. code-block:: php
 
         // app/config/config.php
         $container->loadFromExtension('framework', array(
-            'translator' => array('fallback' => 'en'),
+            'translator' => array('fallbacks' => array('en')),
         ));
 
-See :ref:`book-translation-fallback` for details on the ``fallback`` key
+See :ref:`book-translation-fallback` for details on the ``fallbacks`` key
 and what Symfony does when it doesn't find a translation.
 
 The locale used in translations is the one stored on the request. This is
@@ -403,7 +405,7 @@ checks translation resources for several locales:
 #. If it wasn't found, Symfony looks for the translation in a ``fr`` translation
    resource (e.g. ``messages.fr.xliff``);
 
-#. If the translation still isn't found, Symfony uses the ``fallback`` configuration
+#. If the translation still isn't found, Symfony uses the ``fallbacks`` configuration
    parameter, which defaults to ``en`` (see `Configuration`_).
 
 .. _book-translation-user-locale:

quick_tour/the_architecture.rst

@@ -145,7 +145,7 @@ PHP. Have a look at this sample of the default Symfony configuration:
 
     framework:
         #esi:             ~
-        #translator:      { fallback: "%locale%" }
+        #translator:      { fallbacks: ["%locale%"] }
         secret:          "%secret%"
         router:
             resource: "%kernel.root_dir%/config/routing.yml"

reference/configuration/framework.rst

@@ -48,7 +48,7 @@ Configuration
     * :ref:`enabled <profiler.enabled>`
 * `translator`_
     * :ref:`enabled <translator.enabled>`
-    * `fallback`_
+    * `fallbacks`_
 * `validation`_
     * :ref:`enabled <validation-enabled>`
     * `cache`_
@@ -564,10 +564,19 @@ enabled
 
 Whether or not to enable the ``translator`` service in the service container.
 
-fallback
-........
+.. _fallback:
 
-**type**: ``string`` **default**: ``en``
+fallbacks
+.........
+
+**type**: ``string|array`` **default**: ``array('en')``
+
+.. versionadded:: 2.3.25
+    The ``fallbacks`` option was introduced in Symfony 2.3.25. Prior
+    to Symfony 2.3.25, it was called ``fallback`` and only allowed one fallback
+    language defined as a string.
+    Please note that you can still use the old ``fallback`` option if you want
+    define only one fallback.
 
 This option is used when the translation key for the current locale wasn't found.
 
@@ -724,7 +733,7 @@ Full default Configuration
             # translator configuration
             translator:
                 enabled:              false
-                fallback:             en
+                fallbacks:            [en]
 
             # validation configuration
             validation: