minor #8733 Updated the translation/* articles to Symfony 4 (javiereguiluz)

This PR was squashed before being merged into the 4.0 branch (closes #8733).

Discussion
----------

Updated the translation/* articles to Symfony 4

Commits
-------

eb93259 Fixes after Ryan's remarks
aec8b0e Tweaks
8fe3cf0 Updated the translation/* articles to Symfony 4

Author: weaverryan

_images/translation/debug_1.png

@@ -48,24 +48,36 @@ to learn even more. Overall, the process has several steps:
 
 .. _translation-configuration:
 
+Installation
+------------
+
+First, run this command to install the translator before using it:
+
+.. code-block:: terminal
+
+    $ composer require translator
+
 Configuration
 -------------
 
-Translations are handled by a ``translator`` service that uses the user's
-locale to lookup and return translated messages. Before using it, enable the
-``translator`` in your configuration:
+The previous command creates an initial config file where you can define the
+default locale of the app and the :ref:`fallback locales <translation-fallback>`
+ that will be used if Symfony can't find some translation:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        # app/config/config.yml
+        # config/packages/translation.yaml
         framework:
-            translator: { fallbacks: [en] }
+            default_locale: 'en'
+            translator:
+                fallbacks: ['en']
+                # ...
 
     .. code-block:: xml
 
-        <!-- app/config/config.xml -->
+        <!-- config/packages/translation.xml -->
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -75,23 +87,23 @@ locale to lookup and return translated messages. Before using it, enable the
                 http://symfony.com/schema/dic/symfony
                 http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
 
-            <framework:config>
+            <framework:config default-locale="en">
                 <framework:translator>
                     <framework:fallback>en</framework:fallback>
+                    <!-- ... -->
                 </framework:translator>
             </framework:config>
         </container>
 
     .. code-block:: php
 
-        // app/config/config.php
+        // config/packages/translation.php
         $container->loadFromExtension('framework', array(
+            'default_locale' => 'en',
             'translator' => array('fallbacks' => array('en')),
+            // ...
         ));
 
-See :ref:`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
 typically set via a ``_locale`` attribute on your routes (see :ref:`translation-locale-url`).
 
@@ -108,10 +120,11 @@ for example, that you're translating a simple message from inside a controller::
 
     // ...
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Translation\Translator;
 
-    public function indexAction()
+    public function index(Translator $translator)
     {
-        $translated = $this->get('translator')->trans('Symfony is great');
+        $translated = $translator->trans('Symfony is great');
 
         return new Response($translated);
     }
@@ -129,7 +142,7 @@ different formats, XLIFF being the recommended format:
 
     .. code-block:: xml
 
-        <!-- messages.fr.xlf -->
+        <!-- translations/messages.fr.xlf -->
         <?xml version="1.0"?>
         <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
             <file source-language="en" datatype="plaintext" original="file.ext">
@@ -144,12 +157,12 @@ different formats, XLIFF being the recommended format:
 
     .. code-block:: yaml
 
-        # messages.fr.yml
+        # translations/messages.fr.yml
         Symfony is great: J'aime Symfony
 
     .. code-block:: php
 
-        // messages.fr.php
+        // translations/messages.fr.php
         return array(
             'Symfony is great' => 'J\'aime Symfony',
         );
@@ -186,10 +199,11 @@ Message Placeholders
 Sometimes, a message containing a variable needs to be translated::
 
     use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Translation\Translator;
 
-    public function indexAction($name)
+    public function index(Translator $translator, $name)
     {
-        $translated = $this->get('translator')->trans('Hello '.$name);
+        $translated = $translator->trans('Hello '.$name);
 
         return new Response($translated);
     }
@@ -336,14 +350,14 @@ Translation Resource/File Names and Locations
 
 Symfony looks for message files (i.e. translations) in the following default locations:
 
-* the ``app/Resources/translations`` directory;
+* the ``translations/`` directory;
 
-* the ``app/Resources/<bundle name>/translations`` directory;
+* the ``src/Resources/<bundle name>/translations/`` directory;
 
 * the ``Resources/translations/`` directory inside of any bundle.
 
 The locations are listed here with the highest priority first. That is, you can
-override the translation messages of a bundle in any of the top 2 directories.
+override the translation messages of a bundle in any of the top two directories.
 
 The override mechanism works at a key level: only the overridden keys need
 to be listed in a higher priority message file. When a key is not found
@@ -359,14 +373,14 @@ must be named according to the following path: ``domain.locale.loader``:
 * **locale**: The locale that the translations are for (e.g. ``en_GB``, ``en``, etc);
 
 * **loader**: How Symfony should load and parse the file (e.g. ``xlf``,
-  ``php``, ``yml``, etc).
+  ``php``, ``yaml``, etc).
 
 The loader can be the name of any registered loader. By default, Symfony
 provides many loaders, including:
 
 * ``xlf``: XLIFF file;
 * ``php``: PHP file;
-* ``yml``: YAML file.
+* ``yaml``: YAML file.
 
 The choice of which loader to use is entirely up to you and is a matter of
 taste. The recommended option is to use ``xlf`` for translations.
@@ -381,15 +395,15 @@ For more options, see :ref:`component-translator-message-catalogs`.
 
         .. code-block:: yaml
 
-            # app/config/config.yml
+            # config/packages/translation.yaml
             framework:
                 translator:
                     paths:
-                        - '%kernel.project_dir%/translations'
+                        - '%kernel.project_dir%/custom/path/to/translations'
 
         .. code-block:: xml
 
-            <!-- app/config/config.xml -->
+            <!-- config/packages/translation.xml -->
             <?xml version="1.0" encoding="UTF-8" ?>
             <container xmlns="http://symfony.com/schema/dic/services"
                 xmlns:framework="http://symfony.com/schema/dic/symfony"
@@ -402,18 +416,18 @@ For more options, see :ref:`component-translator-message-catalogs`.
 
                 <framework:config>
                     <framework:translator>
-                        <framework:path>%kernel.project_dir%/translations</framework:path>
+                        <framework:path>%kernel.project_dir%/custom/path/to/translations</framework:path>
                     </framework:translator>
                 </framework:config>
             </container>
 
         .. code-block:: php
 
-            // app/config/config.php
+            // config/packages/translation.php
             $container->loadFromExtension('framework', array(
                 'translator' => array(
                     'paths' => array(
-                        '%kernel.project_dir%/translations',
+                        '%kernel.project_dir%/custom/path/to/translations',
                     ),
                 ),
             ));
@@ -455,7 +469,7 @@ checks translation resources for several locales:
 
 .. note::
 
-    When Symfony doesn't find a translation in the given locale, it will
+    When Symfony can't find a translation in the given locale, it will
     add the missing translation to the log file. For details,
     see :ref:`reference-framework-translator-logging`.
 
@@ -504,9 +518,10 @@ Learn more
 
 .. toctree::
     :maxdepth: 1
-    :glob:
 
-    /translation/*
+    translation/locale
+    translation/debug
+    translation/lint
 
 .. _`i18n`: https://en.wikipedia.org/wiki/Internationalization_and_localization
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes