Some general fixes/improvements for translation guide

wouterj · wouterj · commit a6dabc1d8fd0 · 2019-05-04T18:39:03.000+02:00
diff --git a/translation.rst b/translation.rst
@@ -12,13 +12,11 @@ wrapping each with a function capable of translating the text (or "message")
 into the language of the user::
 
     // text will *always* print out in English
-    dump('Hello World');
-    die();
+    echo 'Hello World';
 
     // text can be translated into the end-user's language or
     // default to English
-    dump($translator->trans('Hello World'));
-    die();
+    echo $translator->trans('Hello World');
 
 .. note::
 
@@ -163,15 +161,15 @@ different formats, XLIFF being the recommended format:
 
         // translations/messages.fr.php
         return [
-            'Symfony is great' => 'J\'aime Symfony',
+            'Symfony is great' => "J'aime Symfony",
         ];
 
 For information on where these files should be located, see
 :ref:`translation-resource-locations`.
 
 Now, if the language of the user's locale is French (e.g. ``fr_FR`` or ``fr_BE``),
 the message will be translated into ``J'aime Symfony``. You can also translate
-the message inside your :ref:`templates <translation-tags>`.
+the message inside your `templates <Translations in Templates>`.
 
 The Translation Process
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -184,7 +182,8 @@ To actually translate the message, Symfony uses the following process:
   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.
+  "dictionary" of translations. This catalog is cached in production, to
+  minimize performance impact.
 
 * If the message is located in the catalog, the translation is returned. If
   not, the translator returns the original message.
@@ -240,112 +239,14 @@ 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:
 
-.. _translation-tags:
+.. code-block:: html+twig
 
-Twig Templates
-~~~~~~~~~~~~~~
+    <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.
-
-.. 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:
-
-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') }}
-
-.. 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:
-
-.. code-block:: html+php
-
-    <?= $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.
 
 Extracting Translation Contents and Updating Catalogs Automatically
 -------------------------------------------------------------------
@@ -381,11 +282,9 @@ Translation Resource/File Names and Locations
 
 Symfony looks for message files (i.e. translations) in the following default locations:
 
-* the ``translations/`` directory (at the root of the project);
-
-* the ``src/Resources/<bundle name>/translations/`` directory;
-
-* the ``Resources/translations/`` directory inside of any bundle.
+#. the ``translations/`` directory (at the root of the project);
+#. the ``src/Resources/<bundle name>/translations/`` directory;
+#. the ``Resources/translations/`` directory inside of any bundle.
 
 .. deprecated:: 4.2
 
@@ -486,6 +385,12 @@ For more options, see :ref:`component-translator-message-catalogs`.
 
         $ php bin/console cache:clear
 
+Handling the User's Locale
+--------------------------
+
+Translating happens based on the user's locale. Read :doc:`/translation/locale`
+to learn more about how to handle it.
+
 .. _translation-fallback:
 
 Fallback Translation Locales
@@ -510,12 +415,6 @@ checks translation resources for several locales:
     add the missing translation to the log file. For details,
     see :ref:`reference-framework-translator-logging`.
 
-Handling the User's Locale
---------------------------
-
-Translating happens based on the user's locale. Read :doc:`/translation/locale`
-to learn more about how to handle it.
-
 Translating Database Content
 ----------------------------
 
@@ -555,6 +454,7 @@ Learn more
 .. toctree::
     :maxdepth: 1
 
+    translation/templates
     translation/locale
     translation/debug
     translation/lint
diff --git a/translation/templates.rst b/translation/templates.rst
@@ -0,0 +1,111 @@
+Using Translation in Templates
+==============================
+
+Twig Templates
+--------------
+
+.. _translation-tags:
+
+Using Twig Tags
+~~~~~~~~~~~~~~~
+
+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.
+
+.. 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') }}
+
+.. 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]
+    ) ?>
