Reword

controller.rst

@@ -623,8 +623,8 @@ For example, imagine you're processing a :doc:`form </forms>` submission::
 
 .. _request-object-info:
 
-The Request Object
-------------------
+The Request and Response Object
+-------------------------------
 
 As mentioned :ref:`earlier <controller-request-argument>`, Symfony will
 pass the ``Request`` object to any controller argument that is type-hinted with
@@ -660,36 +660,6 @@ the ``Request`` class::
 The ``Request`` class has several public properties and methods that return any
 information you need about the request.
 
-For example, the method ``getPreferredLanguage`` accepts an array of preferred languages and
-returns the best language for the user, based on the ``Accept-Language`` header.
-The locale is returned with language, script and region, if available (e.g. ``en_US``, ``fr_Latn_CH`` or ``pt``).
-
-Before Symfony 7.1, this method had the following logic:
-
-1. If no locale is set as a parameter, it returns the first language in the
-   ``Accept-Language`` header or ``null`` if the header is empty
-2. If no ``Accept-Language`` header is set, it returns the first locale passed
-   as a parameter.
-3. If a locale is set as a parameter and in the ``Accept-Language`` header,
-   it returns the first exact match.
-4. Then, it returns the first language passed in the ``Accept-Language`` header or as argument.
-
-Starting from Symfony 7.1, the method has an additional step:
-
-1. If no locale is set as a parameter, it returns the first language in the
-   ``Accept-Language`` header or ``null`` if the header is empty
-2. If no ``Accept-Language`` header is set, it returns the first locale passed
-   as a parameter.
-3. If a locale is set as a parameter and in the ``Accept-Language`` header,
-   it returns the first exact match.
-4. If a language matches the locale, but has a different script or region, it returns the first language in the
-   ``Accept-Language`` header that matches the locale's language, script or region combination
-   (e.g. ``fr_CA`` will match ``fr_FR``).
-5. Then, it returns the first language passed in the ``Accept-Language`` header or as argument.
-
-The Response Object
--------------------
-
 Like the ``Request``, the ``Response`` object has a public ``headers`` property.
 This object is of the type :class:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag`
 and provides methods for getting and setting response headers. The header names are

translation.rst

@@ -981,6 +981,25 @@ the framework:
 This ``default_locale`` is also relevant for the translator, as shown in the
 next section.
 
+Selecting the Language Preferred by the User
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your application supports multiple languages, the first time a user visits your
+site it's common to redirect them to the best possible language according to their
+preferences. This is achieved with the ``getPreferredLanguage()`` method of the
+:ref:`Request object <controller-request-argument>`::
+
+    // get the Request object somehow (e.g. as a controller argument)
+    $request = ...
+    // pass an array of the locales (their script and region parts are optional) supported
+    // by your application and the method returns the best locale for the current user
+    $locale = $request->getPreferredLanguage(['pt', 'fr_Latn_CH', 'en_US'] );
+
+Symfony finds the best possible language based on the locales passed as argument
+and the value of the ``Accept-Language`` HTTP header. If it can't find a perfect
+match between them, this method returns the first locale passed as argument
+(that's why the order of the passed locales is important).
+
 .. _translation-fallback:
 
 Fallback Translation Locales