refactor(reference): document kernel.locale_aware

Author: Guikingone

reference/dic_tags.rst

@@ -26,6 +26,7 @@ Tag Name                                  Usage
 `kernel.event_listener`_                  Listen to different events/hooks in Symfony
 `kernel.event_subscriber`_                To subscribe to a set of different events/hooks in Symfony
 `kernel.fragment_renderer`_               Add new HTTP content rendering strategies
+`kernel.locale_aware`_                    To interact with the locale
 `kernel.reset`_                           Allows to clean up services between requests
 `mime.mime_type_guesser`_                 Add your own logic for guessing MIME types
 `monolog.logger`_                         Logging with a custom logging channel
@@ -470,6 +471,77 @@ To add a new rendering strategy - in addition to the core strategies like
 :class:`Symfony\\Component\\HttpKernel\\Fragment\\FragmentRendererInterface`,
 register it as a service, then tag it with ``kernel.fragment_renderer``.
 
+kernel.locale_aware
+-------------------
+
+.. versionadded:: 4.3
+
+    The ``kernel.locale_aware`` tag was introduced in Symfony 4.3.
+
+**Purpose**: To interact with the locale
+
+Setting and retrieving the locale can be done via the configuration or
+thanks to container parameters or even listeners / route parameters.
+
+Thanks to the ``Translation`` contract, the locale can be set via services.
+
+To register your own locale aware service, first create a service that implements
+the :class:`Symfony\\Contracts\\Translation\\LocaleAwareInterface` interface::
+
+    // src/Locale/MyCustomLocaleHandler.php
+    namespace App\Locale;
+
+    use Symfony\Contracts\Translation\LocaleAwareInterface;
+
+    class MyCustomLocaleHandler implements LocaleAwareInterface
+    {
+        public function setLocale($locale)
+        {
+            // ... do some sort of operations to set the locale
+        }
+
+        public function getLocale()
+        {
+            return 'en';
+        }
+    }
+
+If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
+your service will be automatically tagged with ``kernel.locale_aware``. But, you
+can also register it manually:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            App\Locale\MyCustomLocaleHandler:
+                tags: [kernel.locale_aware]
+
+    .. code-block:: 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"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="App\Locale\MyCustomLocaleHandler">
+                    <tag name="kernel.locale_aware"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        use App\Locale\MyCustomLocaleHandler;
+
+        $container
+            ->register(LocaleHandler::class)
+            ->addTag('kernel.locale_aware')
+        ;
+
 kernel.reset
 ------------