minor #15942 [HttpKernel] Add basic support for language negotiation (hiddewie)

javiereguiluz · javiereguiluz · commit 0b2f05a1f8c7 · 2021-10-19T15:24:33.000+02:00
This PR was squashed before being merged into the 5.4 branch. Discussion ---------- [HttpKernel] Add basic support for language negotiation From symfony/symfony#43108 Fixes #15891 I moved the documentation for the deprecated option with a deprecation notice at the old place. The new options `set_content_language_from_locale` and `set_locale_from_accept_language` have been documented. Commits ------- c41db2f [HttpKernel] Add basic support for language negotiation
diff --git a/performance.rst b/performance.rst
@@ -43,7 +43,7 @@ features, such as the APCu Cache adapter.
 Restrict the Number of Locales Enabled in the Application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Use the :ref:`framework.translator.enabled_locales <reference-translator-enabled-locales>`
+Use the :ref:`framework.enabled_locales <reference-enabled-locales>`
 option to only generate the translation files actually used in your application.
 
 .. _performance-service-container-single-file:
@@ -115,7 +115,7 @@ Symfony generates a file with the list of classes to preload in the
 
     ; php.ini
     opcache.preload=/path/to/project/config/preload.php
-    
+
     ; required for opcache.preload:
     opcache.preload_user=www-data
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -282,6 +282,87 @@ method.
     You can read more information about the default locale in
     :ref:`translation-default-locale`.
 
+.. _reference-enabled-locales:
+
+enabled_locales
+...............
+
+**type**: ``array`` **default**: ``[]`` (empty array = enable all locales)
+
+.. versionadded:: 5.1
+
+    The ``enabled_locales`` option was introduced in Symfony 5.1.
+
+Symfony applications generate by default the translation files for validation
+and security messages in all locales. If your application only uses some
+locales, use this option to restrict the files generated by Symfony and improve
+performance a bit:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/translation.yaml
+        framework:
+            enabled_locales: ['en', 'es']
+
+    .. code-block:: xml
+
+        <!-- config/packages/translation.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"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <enabled-locale>en</enabled-locale>
+                <enabled-locale>es</enabled-locale>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/translation.php
+        use Symfony\Config\FrameworkConfig;
+
+        return static function (FrameworkConfig $framework) {
+            $framework->enabledLocales(['en', 'es']);
+        };
+
+If some user makes requests with a locale not included in this option, the
+application won't display any error because Symfony will display contents using
+the fallback locale.
+
+set_content_language_from_locale
+...............
+
+**type**: ``boolean`` **default**: ``false``
+
+.. versionadded:: 5.4
+
+    The ``set_content_language_from_locale`` option was introduced in Symfony 5.4.
+
+If this option is set to ``true``, the response will have a ``Content-Language``
+HTTP header set with the ``Request`` locale.
+
+set_locale_from_accept_language
+...............
+
+**type**: ``boolean`` **default**: ``false``
+
+.. versionadded:: 5.4
+
+    The ``set_locale_from_accept_language`` option was introduced in Symfony 5.4.
+
+The ``Request`` locale will automatically be set to the value of the
+``Accept-Language`` HTTP header.
+
+When the ``_locale`` request attribute is passed, the ``Accept-Language`` header
+is ignored.
+
 disallow_search_engine_index
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -2142,52 +2223,10 @@ enabled_locales
 
     The ``enabled_locales`` option was introduced in Symfony 5.1.
 
-Symfony applications generate by default the translation files for validation
-and security messages in all locales. If your application only uses some
-locales, use this option to restrict the files generated by Symfony and improve
-performance a bit:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # config/packages/translation.yaml
-        framework:
-            translator:
-                enabled_locales: ['en', 'es']
-
-    .. code-block:: xml
+.. deprecated:: 5.4
 
-        <!-- config/packages/translation.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"
-            xmlns:framework="http://symfony.com/schema/dic/symfony"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services
-                https://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
-
-            <framework:config>
-                <framework:translator>
-                    <enabled-locale>en</enabled-locale>
-                    <enabled-locale>es</enabled-locale>
-                </framework:translator>
-            </framework:config>
-        </container>
-
-    .. code-block:: php
-
-        // config/packages/translation.php
-        use Symfony\Config\FrameworkConfig;
-
-        return static function (FrameworkConfig $framework) {
-            $framework->translator()
-                ->enabledLocales(['en', 'es']);
-        };
-
-If some user makes requests with a locale not included in this option, the
-application won't display any error because Symfony will display contents using
-the fallback locale.
+    Using `framework.translator.enabled_locales` has been deprecated in favour of
+    :ref:`framework.enabled_locales <reference-enabled-locales>` since Symfony 5.4.
 
 .. _fallback:
 
