feat!: add useSetI18nParams composable

[BobbieGoede]

🔗 Linked issue

• Dynamic Routes in Nuxt 3 #2429
• Dynamic route parameters do not work with dynamic values #2006
• Feature: Dynamic route parameters should not be set using definePageMeta #1736

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 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)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

• Depends on feat: dynamic params interceptor intlify/routing#82
• Still could add more tests.

This PR adds a composable useSetI18nParams which returns a function setI18nParams which can be used to set the translated parameters for the current route.

// `products/[slug].vue` (current page='/en/products/red-mug')
 
const setI18nParams = useSetI18nParams();
setI18nParams({
  en: {
    slug: 'red-mug'
  },
  nl: {
    slug: 'rode-mok'
  }
})

The composable function logic is basically a reimplementation of useLocaleHead from vue-i18n-routing except it uses Nuxt's built in unhead instance to manage and render the tags.

This PR only works combined with intlify/routing#82, as this allows us to change where these dynamic translated parameters are sourced from. In this implementation it uses useState to set and retrieve these parameters, which seems to work in my testing.

There is likely a better solution for this, but I hope to find a way to resolve the linked issues as I think this is/would be blocking users from moving to v8. If this works, we can always improve the functionality or performance later.

Goal

I have removed references to using dynamic parameters with definePageMeta, the issue with using definePageMeta is that it's fixed at build time.

Workarounds described #1736 bypass this by setting route.meta.nuxtI18n directly, this works except for updating the SEO tags during SSR, this PR works similar to the workarounds except SEO tags are updated and rendered on the server.

The issue described below also applies to those workarounds.

Common issue

In the documentation I have added a warning about a common scenario as there is no reactivity during SSR. For example, setting dynamic parameters from within a page will not be reflected in a layout as it would have already been rendered (see this comment). This will cause a hydration mismatch if a language switcher is present in a layout or any page or component that renders before setting dynamic parameters. This has been improved to match the workaround, hydration mismatch is avoided as links will be retroactively updated on the client side, this means not all links are rendered correctly on the server-side while the head tags are.

Remarks

• I haven't removed the logic of dynamic parameters using definePageMeta as that would make this a breaking PR. should this be fully removed and/or trigger a deprecation warning when still in use? I have added deprecation warnings which log which pages are using the deprecated method.
• In the future I would like to improve and implement this in vue-i18n-routing, as unhead can be used there as well. It's not my intention to move code out of that repository, but the current implementation makes use of Nuxt's unhead instance.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[nuxt-studio]

✅ Live Preview ready!

Name	Edit	Preview	Latest Commit
i18n	Edit on Studio ↗︎	View Live Preview	33933c6

[kazupon]

Great work!
I've just reviewed your PR!
Please check it!

[BobbieGoede]

Thanks for the feedback! I agree that it's better to keep the docs and refer to the new composable, and add warnings when using the deprecated functionality.

After more testing with this PR I ran into some SSR/hydration issues that I would like to fix as well. It will take some time to figure out the issues and to make the suggested changes so I'm marking this PR as WIP in the meantime!

[BobbieGoede]

While trying to debug the hydration issues I found out I overcomplicated the solution a bit by using useState. This feature now internally uses the nuxtI18n approach, but improves its usage and ensures the meta tags are updated. I think there are a few ways to improve on the current way we handle head tags, but that will be something I can focus on aftwards.

@kazupon
I have added the deprecation warnings in the documentation and also added the warning logs when usage is detected, should I add tests to confirm these logs are working as expected? And should it be possible to disable this logs?

[kazupon]

Great works!
LGTM!

[kazupon]

@BobbieGoede

should I add tests to confirm these logs are working as expected? And should it be possible to disable this logs?

The logging test should be added if possible.
As far as I know, warning can be disabled by specifying it in the useLogger options.
https://nuxt.com/docs/api/kit/logging

useLogger uses consola, I think it may be possible to disable it by setting an ENV or log level.
https://github.com/unjs/consola

[BobbieGoede]

@kazupon

The logging test should be added if possible.

Okay add those soon!

I think I will also change the arguments passed to useSetI18nParams, so that instead of { addDirAttribute?: boolean, addSeoAttribute?: boolean | SeoAttributesOptions } it will accept SeoAttributesOptions | undefined. Reasoning behind it is that this function shouldn't change the dir attribute (will remove that), and right now if addSeoAttribute isn't passed the function won't do anything.

[BobbieGoede]

@kazupon
Actually I don't know how to test those logs as they happen at build time 😅

useLogger uses consola, I think it may be possible to disable it by setting an ENV or log level.
unjs/consola

Not sure if this is possible, as far as I can tell it is possible to set the log level, but changing it would affect all logs, not just for this module.

I did change the composable parameter as I described.

[kazupon]

@BobbieGoede

Actually I don't know how to test those logs as they happen at build time 😅

I think that we can do test at unit test that work unplugin directly. However, that is really difficult as it requires mock.
we can test the dynamicRouteParams and route.meta.nuxtI18n warning logs at playground.

I've pull the your branch in my local, and I've checked your branch with playground.
I saw the warning logs.
I can merge your PR, so it looks good for me. :)

We should release rc.9, because that PR might have still issues.
If there is the issue, just fix it!

[BobbieGoede]

Okay good! I'll merge this and release rc.9 in a moment 💪

[kazupon]

@BobbieGoede
I'll merge your PR!