Rewords

Author: javiereguiluz

translation.rst

@@ -1105,25 +1105,11 @@ Switch Locale Programmatically
 
     The ``LocaleSwitcher`` was introduced in Symfony 6.1.
 
-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.
 
-.. note::
-
-    The LocaleSwitcher will apply the locale at a request level
-    this means that it will be available only for that request. A
-    redirect, for example, will cancel the LocaleSwitcher's effect.
-    For a permanent locale switch between requests see https://symfony.com/doc/current/session.html#making-the-locale-sticky-during-a-user-s-session.
-
-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;
 
@@ -1136,28 +1122,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'
@@ -1175,6 +1156,20 @@ of:
     :method:`Symfony\\Component\\Translation\\LocaleSwitcher::runWithLocale`
     method was introduced in Symfony 6.4.
 
+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