Merge branch '7.2' into 7.3

* 7.2:
  Rewords
  Clarifying LocaleSwitcher's behavior

Author: javiereguiluz

translation.rst

@@ -1177,18 +1177,11 @@ checks translation resources for several locales:
 Switch Locale Programmatically
 ------------------------------
 
-Sometimes you need to change the locale of the application dynamically
-just to run some code. Imagine a console command that renders Twig templates
-of emails in different languages. You need to change the locale only to
-render those templates.
+Sometimes you need to change the application's locale dynamically while running
+some code. For example, a console command that renders email templates in
+different languages. In such cases, you only need to switch the locale temporarily.
 
-The ``LocaleSwitcher`` class allows you to change at once the locale
-of:
-
-* All the services that are tagged with ``kernel.locale_aware``;
-* ``\Locale::setDefault()``;
-* If the ``RequestContext`` service is available, the ``_locale``
-  parameter (so urls are generated with the new locale)::
+The ``LocaleSwitcher`` class allows you to do that::
 
     use Symfony\Component\Translation\LocaleSwitcher;
 
@@ -1201,28 +1194,23 @@ of:
 
         public function someMethod(): void
         {
-            // you can get the current application locale like this:
             $currentLocale = $this->localeSwitcher->getLocale();
 
-            // you can set the locale for the entire application like this:
-            // (from now on, the application will use 'fr' (French) as the
-            // locale; including the default locale used to translate Twig templates)
+            // set the application locale programmatically to 'fr' (French):
+            // this affects translation, URL generation, etc.
             $this->localeSwitcher->setLocale('fr');
 
-            // reset the current locale of your application to the configured default locale
-            // in config/packages/translation.yaml, by option 'default_locale'
+            // reset the locale to the default one configured via the
+            // 'default_locale' option in config/packages/translation.yaml
             $this->localeSwitcher->reset();
 
-            // you can also run some code with a certain locale, without
+            // run some code with a specific locale, temporarily, without
             // changing the locale for the rest of the application
             $this->localeSwitcher->runWithLocale('es', function() {
-
-                // e.g. render here some Twig templates using 'es' (Spanish) locale
-
+                // e.g. render templates, send emails, etc. using the 'es' (Spanish) locale
             });
 
-            // you can optionally declare an argument in your callback to receive the
-            // injected locale
+            // optionally, receive the current locale as an argument:
             $this->localeSwitcher->runWithLocale('es', function(string $locale) {
 
                 // here, the $locale argument will be set to 'es'
@@ -1233,6 +1221,20 @@ of:
         }
     }
 
+The ``LocaleSwitcher`` class changes the locale of:
+
+* All services tagged with ``kernel.locale_aware``;
+* The default locale set via ``\Locale::setDefault()``;
+* The ``_locale`` parameter of the ``RequestContext`` service (if available),
+  so generated URLs reflect the new locale.
+
+.. note::
+
+    The LocaleSwitcher applies the new locale only for the current request,
+    and its effect is lost on subsequent requests, such as after a redirect.
+
+    See :ref:`how to make the locale persist across requests <locale-sticky-session>`.
+
 When using :ref:`autowiring <services-autowire>`, type-hint any controller or
 service argument with the :class:`Symfony\\Component\\Translation\\LocaleSwitcher`
 class to inject the locale switcher service. Otherwise, configure your services