[DRAFT] feat: experimental route resolution enhancement

[BobbieGoede]

Originally #3358

This functionality is based on the proposed method of resolving routes as seen in the I18n Routing RFC, see the Resolving routes (methods) section.

Todo

• Add tests
• Add overloads router.resolve type
• Document option and usage
• Extract into separate runtime plugin (research)

Description

This adds an experimental feature which changes the behavior of Vue Router's router.resolve to resolve localized routes, this can be configured with experimental.routeResolutionEnhancement.

Configuration

type NuxtI18nOptions = {
  experimental?: {
    routeResolutionEnhancement: false | 'explicit' | 'implicit'
  }
}

false (default)

Disables the feature.

'explicit' (recommended for now)

Route resolution is localized when explicitly opting into the behavior by passing an object with { locale: true | Locale } as third argument.

const router = useRouter();
router.resolve('news') // { path: '/news', ... } (unchanged)
router.resolve('news', null, { locale: true }) // { path: '/en/news', ... } (detected)
router.resolve('news', null, { locale: 'nl' }) // { path: '/nl/news', ... } (passed locale)
router.resolve('news', null, { locale: false }) // { path: '/news', ... } (unchanged, explicit opt-out)

'implicit'

Route resolution is localized by default, can be explicitly disabled by passing { locale: false } as third argument.

const router = useRouter();
router.resolve('news') // { path: '/en/news', ... } (implicit, detected)
router.resolve('news', null, { locale: true }) // { path: '/en/news', ... } (detected)
router.resolve('news', null, { locale: 'nl' }) // { path: '/nl/news', ... } (passed locale)
router.resolve('news', null, { locale: false }) // { path: '/news', ... } (unchanged, explicit opt-out)

Compatibility

The 'implicit' enhancement is most powerful as it changes all route resolution in a project to be localized, this could be an issue for modules/plugins and cross project code/tests.

Explicitly opting out of the localized resolution would be necessary to preserve the same (predictable) behavior regardless of the configured enhancement option, this is used internally in this module for localized resolution as well.

Considerations

Ironically, the 'implicit' option could be problematic for projects that already use this module since we have no control over NuxtLink. If localized links are set up using localePath (e.g. <NuxtLink :to="localePath(..., locale)"/>), the implicit localization will default to the current locale within the NuxtLink component, losing the explicitly passed locale.

In that case users can either use localeRoute instead of localePath as it passes an object (with correct localized name prop) or use the NuxtLinkLocale component.

There may be other scenarios where the implicit route localization could cause unexpected behavior, the easiest way to find out is by testing the experimental options in real projects.