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

[nicwortel]

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)). 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 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.

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.

[xabbuh]

What about adding a code example instead? This could make the effect more clear (and we can still explain it with an inline comment)?

[nicwortel]

Yeah I considered that, but as it makes the tip bigger I thought it would distract too much from the main content.

But I could indeed add an example of a route that defines the locale parameter. Do you think I should use only an attribute as an example (as the YAML, XML and PHP examples in the block above all import the Controller directory with type: attribute)? Or should I include examples in YAML, XML & PHP as well?

The example for using attributes could look something like this:

class EnglishArticleController extends AbstractController
{
    #[Route(path: '/articles/english-only', locale: 'en')]
    public function display(): Response
    {
    }
}

Although I need to think about some better class / method / route names to come up with a more real-life example as per the documentation standards.

[smnandre]

I often use the "soccer" / "football" thing to illustrate the "default prefix expect one locale"

• football (default)
• us : soccer

In the opposite situation, i guess you could use services in ecommerce that are often restricted to the country where the shop operates, like "express-delivery", cashback options, .. etc ?

[nicwortel]

I have added an example with annotations and with attributes. I'm not sure if I should add examples for YAML, XML and PHP as well?

[javiereguiluz]

Thanks Nic! This is finally merged.

Note that while merging I did some changes:

• I removed the route definition example because it looked confusing to have it (it's just a normal route definition)
• I reworded a bit the explanation to show an example (without code) similar to the example that you created: an English only route that is not imported for nl prefix, only for en