[Translation] document LocaleSwitcher

Author: kbond

translation.rst

@@ -827,6 +827,58 @@ checks translation resources for several locales:
     add the missing translation to the log file. For details,
     see :ref:`reference-framework-translator-logging`.
 
+Switch Locale Programmatically
+------------------------------
+
+.. versionadded:: 6.1
+
+    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.
+
+The ``LocaleSwitcher`` object/service allows you to change at once the locale
+of:
+
+1. All the services that are tagged with ``kernel.locale_aware``.
+2. ``\Locale::setDefault()``.
+3. If a request is available, the ``_locale`` request attribute.
+
+The ``LocaleSwitcher`` service is autowireable and can be injected into other
+services::
+
+    use Symfony\Component\Translation\LocaleSwitcher;
+
+    class SomeClass
+    {
+        public function __construct(
+            private LocaleSwitcher $localeSwitcher,
+        ) {}
+
+        public function someMethod()
+        {
+            // 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)
+            $this->localeSwitcher->setLocale('fr');
+
+            // you can also run some code with a certain locale, 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
+
+            });
+
+            // ...
+        }
+    }
+
 Translating Database Content
 ----------------------------