Merge branch '4.4' into 5.2

* 4.4:
  [Translation] Move the "templates" section into the main guide
  [Intl] Fix typos
  [Session] Add missing semicolon

Author: javiereguiluz

_build/redirection_map

@@ -459,6 +459,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

components/intl.rst

@@ -110,7 +110,7 @@ to catching the exception, you can also check if a given language code is valid:
 
     $isValidLanguage = Languages::exists($languageCode);
 
-Or if you have a alpha3 language code you want to check::
+Or if you have an alpha3 language code you want to check::
 
     $isValidLanguage = Languages::alpha3CodeExists($alpha3Code);
 
@@ -197,7 +197,7 @@ to catching the exception, you can also check if a given country code is valid::
 
     $isValidCountry = Countries::exists($alpha2Code);
 
-Or if you have a alpha3 country code you want to check::
+Or if you have an alpha3 country code you want to check::
 
     $isValidCountry = Countries::alpha3CodeExists($alpha3Code);
 

session/locale_sticky_session.rst

@@ -109,7 +109,8 @@ via some "Change Locale" route & controller), or create a route with the :ref:`_
             $container->register(LocaleSubscriber::class)
                 ->addArgument('%kernel.default_locale%')
                 // uncomment the next line if you are not using autoconfigure
-                // ->addTag('kernel.event_subscriber');
+                // ->addTag('kernel.event_subscriber')
+            ;
 
 That's it! Now celebrate by changing the user's locale and seeing that it's
 sticky throughout the request.

translation.rst

@@ -337,14 +337,88 @@ 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
+~~~~~~~~~~~~~~~
+
+Symfony provides a specialized Twig tag ``trans`` to help with message
+translation of *static blocks of text*:
+
+.. code-block:: twig
+
+    {% trans %}Hello %name%{% endtrans %}
+
+.. 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 %}
+
+.. _translation-filters:
+
+Using Twig Filters
+~~~~~~~~~~~~~~~~~~
+
+The ``trans`` filter can be used to translate *variable texts* and complex expressions:
+
+.. code-block:: twig
+
+    {{ message|trans }}
+
+    {{ message|trans({'%name%': 'Fabien'}, 'app') }}
+
+.. 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
+~~~~~~~~~~~~~
 
-    <h1>{% trans %}Symfony is great!{% endtrans %}</h1>
+The translator service is accessible in PHP templates through the
+``translator`` helper::
 
-Read :doc:`/translation/templates` for more information about the Twig tags and
-filters for translation.
+    <?= $view['translator']->trans('Symfony is great') ?>
 
 Forcing the Translator Locale
 -----------------------------
@@ -608,7 +682,6 @@ Learn more
     :maxdepth: 1
 
     translation/message_format
-    translation/templates
     translation/locale
     translation/debug
     translation/lint