docs: Update the description for Negotiation

Author: neznaika0

user_guide_src/source/changelogs/v4.6.0.rst

@@ -242,9 +242,9 @@ Routing
 Negotiator
 ==========
 
-- Added a feature flag ``Feature::$looseLocaleNegotiation`` fix simple locale comparison.
+- Added a feature flag ``Feature::$strictLocaleNegotiation`` to enable strict locale comparision.
   Previously, response with language headers ``Accept-language: en-US,en-GB;q=0.9`` returned the first allowed language ``en`` could instead of the exact language ``en-US`` or ``en-GB``.
-  Set the value to ``false`` to be able to get ``en-*``
+  Set the value to ``true`` to enable comparison not only by language code ('en' - ISO 639-1) but also by regional code ('en-US' - ISO 639-1 plus ISO 3166-1 alpha).
 
 Testing
 =======

user_guide_src/source/incoming/content_negotiation.rst

@@ -102,10 +102,57 @@ and German you would do something like:
 In this example, 'en' would be returned as the current language. If no match is found, it will return the first element
 in the ``$supported`` array, so that should always be the preferred language.
 
+Strict Locale Negotiation
+-------------------------
+
 .. versionadded:: 4.6.0
 
-Disabling the ``Config\Feature::$looseLocaleNegotiation`` value allows you to strictly search for the requested language from the specified territory (``en-*``).
-In the case of a non-strict search, the language may be limited only by the country ``en``. Don't forget to create files for the ``en-*`` locale if you need a translation.
+By default, locale is determined on a lossy comparison basis. So only the first part of the locale string is taken
+into account (language). This is usually sufficient. But sometimes we want to be able to distinguish between regional versions such as
+``en-US`` and ``en-GB`` to serve different content.
+
+For such cases, we have introduced a new setting that can be enabled via ``Config\Feature::$strictLocaleNegotiation``. This will ensure
+that the strict comparison will be made in the first place.
+
+.. note::
+
+    CodeIgniter comes with translations only for primary language tags ('en', 'fr', etc.). So if you enable this feature and your
+    settings in ``Config\App::$supportedLocales`` include regional language tags ('en-US', 'fr-FR', etc.), then keep in mind that
+    if you have your own translation files, you **must also change** the folder names for CodeIgniter's translation files to match
+    what you put in the ``$supportedLocales`` array.
+
+    Now let's consider the below example. The browser's preferred language will be set as this::
+
+    GET /foo HTTP/1.1
+    Accept-Language: fr; q=1.0, en-GB; q=0.5
+
+In this example, the browser would prefer French, with a second choice of English (United Kingdom). Your website on another hand will
+supports German and English (United States):
+
+.. code-block:: php
+
+    $supported = [
+        'de',
+        'en-US',
+    ];
+
+    $lang = $request->negotiate('language', $supported);
+    // or
+    $lang = $negotiate->language($supported);
+
+In this example, 'en-US' would be returned as the current language. If no match is found, it will return the first element
+in the ``$supported`` array. Here is how exactly the locale selection process works.
+
+Even though the 'fr' is preferred by the browser it is not in our ``$supported`` array. The same problem occurs with 'en-GB', but here
+we will be able to search for variants. First, we will fallback to the most general locale (in this case 'en') which again is not in our
+array. Then we will search for the regional locale 'en-'. And that's when our value from the ``$supported`` array will be matched.
+We will return 'en-US'.
+
+So the process of selecting a locale is as follows:
+
+#. strict match ('en-GB') - ISO 639-1 plus ISO 3166-1 alpha-2
+#. general locale match ('en') - ISO 639-1
+#. regional locale match ('en-') - ISO 639-1 plus "wildcard" for ISO 3166-1 alpha-2
 
 Encoding
 ========

user_guide_src/source/installation/upgrade_460.rst

@@ -211,14 +211,14 @@ Config
 
 - app/Config/Feature.php
     - ``Config\Feature::$autoRoutesImproved`` has been changed to ``true``.
-    - ``Config\Feature::$looseLocaleNegotiation`` has been added.
+    - ``Config\Feature::$strictLocaleNegotiation`` has been added.
 - app/Config/Routing.php
     - ``Config\Routing::$translateUriToCamelCase`` has been changed to ``true``.
+
 All Changes
 ===========
 
 This is a list of all files in the **project space** that received changes;
 many will be simple comments or formatting that have no effect on the runtime:
 
-- app/Config/Feature.php
-- @TODO
+- app/Config/Feature.php