feat: experimental typed routes

[BobbieGoede]

🔗 Linked issue

• Support typed routes inside localePath() #2813
• useRoute('login') does not work, it expects useRoute('login__LOCALE') #2976

❓ Type of change

• 📖 Documentation (updates to the documentation, readme or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Important

Very experimental and relies on nuxt/router/uvr internals, this will not be backported to v8.

I'm not very happy with the implementation right now, but it does work... I think the demand/convenience of this feature somewhat justifies adding this albeit under an experimental flag.

We should communicate very clearly that this relies on internals of Nuxt, Vue Router and unplugin-vue-router, perhaps we can make the types fallback to original behavior on failure (maybe it already does). A proper implementation will likely require collaboration with the maintainers of those packages, we should not expect this to keep working as is.

This will need some documentation and basic tests so we know things fail if internals have changed.

Demo stackblitz project here: https://stackblitz.com/edit/bobbiegoede-nuxt-i18n-starter-srohiz?file=nuxt.config.ts&file=composables%2Ftest.ts

Demo of localePath autocompletion

Code_2024-09-27_12-02-50.mp4

Demo of custom routes configuration autocompletion and basic validation (prefix '/')

Code_2024-09-27_12-06-59.mp4

📝 Checklist

• I have linked an issue or discussion.
• I have added tests (if possible).
• I have updated the documentation accordingly.

[pkg-pr-new]

Open in Stackblitz

pnpm add https://pkg.pr.new/@nuxtjs/i18n@3142

commit: 352ce15

[kazupon]

wow! This typing is too amazing!

[BobbieGoede]

I should reference the original source types 😅 I had to redefine/reimplement a bunch of internal types of vue-router and uvr, so the credits for these go to @posva

[kazupon]

I've just reviewed your PR!
It's an excellent for me!

[kazupon]

Since it uses the vue-router type, it would be good if posva is able to review it.

@posva
Can you review it ?, if you have the time 🙏

[BobbieGoede]

@userquin
If you see some obvious structural improvements, feel free to suggest them, the must be some way to leave out the augmentations in internal-global-types.d.ts 🤔

[posva]

Isn't this the same type exported by the router?

[BobbieGoede]

Hmm most of the types should be the same except suffixed with I18n, which this type seems to be missing. This might conflict with existing router types 🫣 going to look into it.

Reasoning behind redefining the same types but suffixed is to use the RouteMapI18n type, perhaps there's a better way to go about this that I'm unaware of.

[posva]

Doesn’t extending the same route map from Vue router works? Or do you need to have two separate route maps?

[BobbieGoede]

Since we're generating routes for each locale (depending on the routing strategy) and custom localized route the generated types are localized, this PR generates RouteMapI18n (which ironically contains the routes without localization) to be used for the i18n routing utility functions.

Some examples to illustrate the problem we're trying to solve:

Named route completion

Path completion (not desirable when using custom routes)

I guess this is specific to i18n, I doubt there are other use cases where generating a separate map is necessary 🤔

[posva]

I would need to try it out to see the needed final types. I was hoping the types were flexible enough to at least keep things typer for the router methods. I18n methods could use extra types for localized route names (that seems to be the main difference)