minor #15094 [Translation] Move the "templates" section into the main guide (Nyholm)

This PR was squashed before being merged into the 4.4 branch.

Discussion
----------

[Translation] Move the "templates" section into the main guide

I would like to move this small page to the main guide about translation. The majority of translation is used in Twig, so it makes little sense no to mention it properly.

Commits
-------

d24d45c [Translation] Move the "templates" section into the main guide

Author: javiereguiluz

_build/redirection_map

@@ -458,6 +458,7 @@
 /templating/embedding_controllers /templates#embedding-controllers
 /templating/inheritance /templates#template-inheritance-and-layouts
 /testing/doctrine /testing/database
+/translation/templates /translation#translation-in-templates
 /doctrine/lifecycle_callbacks /doctrine/events
 /doctrine/event_listeners_subscribers /doctrine/events
 /doctrine/common_extensions /doctrine

translation.rst

@@ -304,14 +304,124 @@ Translations in Templates
 -------------------------
 
 Most of the time, translation occurs in templates. Symfony provides native
-support for both Twig and PHP templates:
+support for both Twig and PHP templates.
 
-.. code-block:: html+twig
+Using Twig Tags
+~~~~~~~~~~~~~~~
 
-    <h1>{% trans %}Symfony is great!{% endtrans %}</h1>
+Symfony provides specialized Twig tags (``trans`` and ``transchoice``) to
+help with message translation of *static blocks of text*:
+
+.. code-block:: twig
+
+    {% trans %}Hello %name%{% endtrans %}
+
+    {% transchoice count %}
+        {0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples
+    {% endtranschoice %}
+
+The ``transchoice`` tag automatically gets the ``%count%`` variable from
+the current context and passes it to the translator. This mechanism only
+works when you use a placeholder following the ``%var%`` pattern.
+
+.. deprecated:: 4.2
+
+    The ``transchoice`` tag is deprecated since Symfony 4.2 and will be
+    removed in 5.0. Use the :doc:`ICU MessageFormat </translation/message_format>` with
+    the ``trans`` tag instead.
+
+.. caution::
+
+    The ``%var%`` notation of placeholders is required when translating in
+    Twig templates using the tag.
+
+.. tip::
+
+    If you need to use the percent character (``%``) in a string, escape it by
+    doubling it: ``{% trans %}Percent: %percent%%%{% endtrans %}``
+
+You can also specify the message domain and pass some additional variables:
+
+.. code-block:: twig
+
+    {% trans with {'%name%': 'Fabien'} from 'app' %}Hello %name%{% endtrans %}
+
+    {% trans with {'%name%': 'Fabien'} from 'app' into 'fr' %}Hello %name%{% endtrans %}
+
+    {% transchoice count with {'%name%': 'Fabien'} from 'app' %}
+        {0} %name%, there are no apples|{1} %name%, there is one apple|]1,Inf[ %name%, there are %count% apples
+    {% endtranschoice %}
+
+.. _translation-filters:
+
+Using Twig Filters
+~~~~~~~~~~~~~~~~~~
+
+The ``trans`` and ``transchoice`` filters can be used to translate *variable
+texts* and complex expressions:
+
+.. code-block:: twig
+
+    {{ message|trans }}
+
+    {{ message|transchoice(5) }}
+
+    {{ message|trans({'%name%': 'Fabien'}, 'app') }}
+
+    {{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
+
+.. deprecated:: 4.2
+
+    The ``transchoice`` filter is deprecated since Symfony 4.2 and will be
+    removed in 5.0. Use the :doc:`ICU MessageFormat </translation/message_format>` with
+    the ``trans`` filter instead.
+
+.. tip::
+
+    Using the translation tags or filters have the same effect, but with
+    one subtle difference: automatic output escaping is only applied to
+    translations using a filter. In other words, if you need to be sure
+    that your translated message is *not* output escaped, you must apply
+    the ``raw`` filter after the translation filter:
+
+    .. code-block:: html+twig
+
+        {# text translated between tags is never escaped #}
+        {% trans %}
+            <h3>foo</h3>
+        {% endtrans %}
+
+        {% set message = '<h3>foo</h3>' %}
+
+        {# strings and variables translated via a filter are escaped by default #}
+        {{ message|trans|raw }}
+        {{ '<h3>bar</h3>'|trans|raw }}
+
+.. tip::
+
+    You can set the translation domain for an entire Twig template with a single tag:
+
+    .. code-block:: twig
+
+       {% trans_default_domain 'app' %}
+
+    Note that this only influences the current template, not any "included"
+    template (in order to avoid side effects).
+
+PHP Templates
+~~~~~~~~~~~~~
+
+The translator service is accessible in PHP templates through the
+``translator`` helper::
+
+    <?= $view['translator']->trans('Symfony is great') ?>
+
+    <?= $view['translator']->transChoice(
+        '{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
+        10,
+        ['%count%' => 10]
+    ) ?>
 
-Read :doc:`/translation/templates` for more information about the Twig tags and
-filters for translation.
 
 Forcing the Translator Locale
 -----------------------------
@@ -600,7 +710,6 @@ Learn more
     :maxdepth: 1
 
     translation/message_format
-    translation/templates
     translation/locale
     translation/debug
     translation/lint