Refactor language URL routing to use explicit @lang special route tokens instead of positional segment detection

[armanist]

Summary

Refactor Quantum language URL routing so routes can explicitly declare language segments using the special route token:

• @lang

instead of relying on positional URL segment detection through config such as lang.url_segment.

Why

Current language URL handling is implicit and positional.

Today, language detection relies on config-driven segment index logic, for example:

• lang.url_segment

and the framework then tries to detect the language by reading a configured request segment position, with additional prefix-aware adjustment logic.

That works, but it has several weaknesses:

• route structure does not explicitly show where language lives
• language handling depends on URL segment position math
• routes are harder to reason about when combined with prefixes or other special segments
• the model does not align with the new special route token direction

With special route token support in place, language routing should become explicit in the route pattern itself.

Goal

Allow routes to explicitly declare the language segment using:

• @lang

so the router can treat language as a framework-owned route context rather than a positional URL convention.

Proposed Direction

Routes that are language-aware should explicitly include:

• @lang

Examples:

$route->get('@lang/posts', 'PostController', 'posts');
$route->get('@lang/post/[uuid=:any]', 'PostController', 'post');

This should allow URLs such as:

• /en/posts
• /es/posts

or, when module prefix is present:

• /web/en/posts
• /api/en/posts

depending on module prefix configuration.

Config Direction

Language config should continue to define language behavior such as:

• whether language is enabled
• supported languages
• default language

But routed language placement should no longer depend on positional config like:

• lang.url_segment

The route itself should explicitly declare where language lives.

Important behavior

The resolved language should be:

• matched through the @lang token
• validated against configured supported languages
• made available to framework internals as language route context
• kept distinct from ordinary controller action parameters by default

Migration Direction

This feature should replace routed language URL detection based on positional segment config for routes that adopt @lang.

Backward compatibility strategy can be decided during implementation, but the intended direction is for explicit routed language segments to become the preferred and cleaner model.

Acceptance Criteria

• routes can explicitly declare language position using @lang
• matched @lang values are validated against configured supported languages
• language route context is resolved through @lang rather than positional URL segment detection for token-based routes
• routed language values do not become ordinary positional controller action parameters by default
• tests cover @lang route matching and language resolution behavior
• templates and examples can be updated to use @lang where appropriate

Notes

Relevant code:

• src/Lang/Factories/LangFactory.php
• src/Router/PatternCompiler.php
• src/Router/MatchedRoute.php
• src/Http/Traits/Request/Route.php
• module route templates currently using language-prefixed route patterns

This ticket depends on:

• #543
• #548