diff --git a/translation.rst b/translation.rst index 72741575376..9b1021948dd 100644 --- a/translation.rst +++ b/translation.rst @@ -827,6 +827,69 @@ 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`` class allows you to change at once the locale +of: + +* All the services that are tagged with ``kernel.locale_aware``; +* ``\Locale::setDefault()``; +* If a request is available, the ``_locale`` request attribute. + +.. code-block:: php + + use Symfony\Component\Translation\LocaleSwitcher; + + class SomeClass + { + private LocaleSwitcher $localeSwitcher; + + public function __construct(LocaleSwitcher $localeSwitcher) + { + $this->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'); + + // reset the current locale of your application to the configured default locale + // in config/packages/translation.yaml, by option 'default_locale' + $this->localeSwitcher->reset(); + + // 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 + + }); + + // ... + } + } + +.. note:: + + The class :class:`Symfony\\Component\\Translation\\LocaleSwitcher` is + autowired to the ``translation.locale_switcher`` service. + Translating Database Content ----------------------------