Consolidate translation docs + review of the contents

Author: fabpot

translation.rst

@@ -103,19 +103,17 @@ are located:
             ;
         };
 
-The locale used in translations is the one stored on the request. This is
-typically set via a ``_locale`` attribute on your routes (see :ref:`translation-locale-url`).
-
 .. _translation-basic:
 
 Basic Translation
 -----------------
 
-Translation of text is done through the  ``translator`` service
-(:class:`Symfony\\Component\\Translation\\Translator`). To translate a block
-of text (called a *message*), use the
+Translation of text is done through the ``translator`` service
+(:class:`Symfony\\Component\\Translation\\Translator`). To translate a block of
+text (called a *message*), use the
 :method:`Symfony\\Component\\Translation\\Translator::trans` method. Suppose,
-for example, that you're translating a static message from inside a controller::
+for example, that you're translating a static message from inside a
+controller::
 
     // ...
     use Symfony\Contracts\Translation\TranslatorInterface;
@@ -251,25 +249,19 @@ The Translation Process
 To actually translate the message, Symfony uses the following process when
 using the ``trans()`` method:
 
-#. The ``locale`` of the current user, which is stored on the request is determined;
+#. The ``locale`` of the current user, which is stored on the request is
+   determined; this is typically set via a ``_locale`` attribute on your routes
+   (see :ref:`translation-locale-url`);
 
-#. A catalog (e.g. big collection) of translated messages is loaded from translation
-   resources defined for the ``locale`` (e.g. ``fr_FR``). Messages from the
-   :ref:`fallback locale <translation-fallback>` are also loaded and
-   added to the catalog if they don't already exist. The end result is a large
-   "dictionary" of translations. This catalog is cached in production to
-   minimize performance impact.
+#. A catalog of translated messages is loaded from translation resources
+   defined for the ``locale`` (e.g. ``fr_FR``). Messages from the
+   :ref:`fallback locale <translation-fallback>` are also loaded and added to
+   the catalog if they don't already exist. The end result is a large
+   "dictionary" of translations.
 
 #. If the message is located in the catalog, the translation is returned. If
    not, the translator returns the original message.
 
-.. tip::
-
-    When translating strings that are not in the default domain (``messages``),
-    you must specify the domain as the third argument of ``trans()``::
-
-        $translator->trans('Symfony is great', [], 'admin');
-
 .. _message-placeholders:
 .. _pluralization:
 
@@ -297,22 +289,6 @@ To manage these situations, Symfony follows the `ICU MessageFormat`_ syntax by
 using PHP's :phpclass:`MessageFormatter` class. Read more about this in
 :doc:`/translation/message_format`.
 
-.. tip::
-
-    If you don't use the ICU MessageFormat syntax in your translation files,
-    pass a parameter named "%count%" to select the best plural form of the message:
-
-    .. code-block:: twig
-
-       {{ message|trans({'%name%': '...', '%count%': 1}, 'app') }}
-
-    The ``message`` variable must include all the different versions of this
-    message based on the value of the ``count`` parameter. For example:
-
-    .. code-block:: text
-
-        {0}%name% has no apples|{1}%name% has one apple|]1,Inf[ %name% has %count% apples
-
 .. _translatable-objects:
 
 Translatable Objects