Changes for `i18next-vue` v3

[kkuegler]

🚀 Proposed changes for i18next-vue v3

For version 3, we'd like to streamline the API of i18next-vue and lean more on the Composition API. Please leave your feedback below.

[Update 2023-08-10] Release 3.0.0 available

We have released version 3.0.0 and a migration guide with the (breaking) changes.

You are still welcome to leave a comment below.

Proposed (breaking) changes

• [update 2023-07-23] This list is now superseded by https://i18next.github.io/i18next-vue/migration-v3.html
• require i18next >=23
• make this package ESM-only
  • this would make it hard for CommonJS users to consume the library
  • this would make the package smaller and easier to maintain
• extend useTranslation() with parameters to specify a fixed language, namespace(s) and a keyprefix (all optional)
  • having this available via the Composition API feels like a clean API
• remove support for i18nOptions in the Options API
  • you could instead use useTranslation() for most of these use-cases
  • update 2023-07-12: we'll probably continue to support everything but messages behind a legacy flag until v4.
• remove support for <i18n> blocks in SFCs
  • apparently there is no compatible Vue 3 loader for this and nobody complained so far
  • Vue 3 loaders like @intlify/unplugin-vue-i18n produce a different, function-based format now, which is not what we want
• remove support for per-component translations
  • that would be the result of removing i18nOptions and <i18n>
  • if there is demand for this, we could re-add per-component messages via useTranslation()
• update 2023-07-12: the translation functions will return an empty string while i18next is not yet initialized
  • before they returned the untranslated translation key, which is usually uglier than an empty string

Your feedback is welcome!

These are all quite big changes if you are relying on them in an existing application. That's why we are looking for your user feedback in this issue as a comment below.

Let us know, which feature you would like to keep, or where you would like some backward compatibility to ease the upgrade process to v3. All of the changes are still up for debate.

Thank you!

[kkuegler]

I talked to some colleagues. They use i18nOptions a lot and almost exclusively to set the keyPrefix for the component. They agree with the general direction of using useTranslation() exclusively for this, but would like a smoother transition, which does not require converting all existing components at once to switch to i18next-vue version 3.

We now have the idea to drop support for i18nOptions messages, but keep supporting the other options under a legacy flag for this plugin. i18nOptions will continue to influence $t for the current component in v3. i18nOptions would no longer influence useTranslation(), which would now use the i18next defaults set in i18next.init() - and of course explicit values (namespace, ...) passed to it.

For the next major version v4 we would then completely drop i18nOptions support. So v3 is a version supporting both, allowing converting components incrementally over to useTranslation().