minor #19825 [Routing] Document the effect of setting locale on a route with locale prefixes (nicwortel)

This PR was squashed before being merged into the 5.4 branch.

Discussion
----------

[Routing] Document the effect of setting `locale` on a route with locale prefixes

When using localized routes and importing a collection of routes, the imported routes can be prefixed with a different prefix for each locale (as documented in [Localized Routes (i18n)](https://symfony.com/doc/current/routing.html#localized-routes-i18n)). This makes it easy to have localized routes for `/en/about-us` and `/nl/over-ons` without having to define multiple routes.

This behavior is implemented in the
[`Symfony\Component\Routing\Loader\Configurator\Traits\PrefixTrait`](https://github.com/symfony/symfony/blob/7.1/src/Symfony/Component/Routing/Loader/Configurator/Traits/PrefixTrait.php) by replacing the original route with a cloned version for each locale prefix.

However, any route which has a default value for the `_locale` parameter [will only be prefixed with the prefix for that locale and will not be cloned for the other locale prefixes](https://github.com/symfony/symfony/blob/39038406d36a4dc1d320ff8d63d9700e7d08045d/src/Symfony/Component/Routing/Loader/Configurator/Traits/PrefixTrait.php#L45-L46).

I stumbled upon this because I was trying to implement a route which should be available only for a single locale. I couldn't find any mention of this behavior in the routing documentation.

Commits
-------

55215ca [Routing] Document the effect of setting `locale` on a route with locale prefixes

Author: javiereguiluz

routing.rst

@@ -2416,6 +2416,54 @@ with a locale. This can be done by defining a different prefix for each locale
             ;
         };
 
+.. tip::
+
+    If the special :ref:`_locale <routing-locale-parameter>` routing parameter
+    is set on any of the imported routes, that route will only be available
+    with the prefix for that locale. This is useful when you want to import
+    a collection of routes which contains a route that should only exist
+    in one of the locales:
+
+    .. configuration-block::
+
+        .. code-block:: php-annotations
+
+            // src/Controller/CompanyController.php
+            namespace App\Controller;
+
+            use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+            use Symfony\Component\HttpFoundation\Response;
+            use Symfony\Component\Routing\Annotation\Route;
+
+            class CompanyController extends AbstractController
+            {
+                /**
+                 * @Route("/about-us/en-only", locale="en", name="about_us")
+                 */
+                public function about(): Response
+                {
+                    // ...
+                }
+            }
+
+        .. code-block:: php-attributes
+
+            // src/Controller/CompanyController.php
+            namespace App\Controller;
+
+            use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+            use Symfony\Component\HttpFoundation\Response;
+            use Symfony\Component\Routing\Annotation\Route;
+
+            class CompanyController extends AbstractController
+            {
+                #[Route('/about-us/en-only', locale: 'en', name: 'about_us')]
+                public function about(): Response
+                {
+                    // ...
+                }
+            }
+
 Another common requirement is to host the website on a different domain
 according to the locale. This can be done by defining a different host for each
 locale.