Move 'Composition API' from 'Advanced' to 'Essentials' section of the docs

[bartenra]

trafficstars

If I read the documentation correctly, the Composition API is now the preferred way to use vue-i18n. Whereas using the Options API is considered 'legacy'. I think over time all the docs will be updated to reflect this. But for now it would make sense to me that it's moved to the 'Essentials' section, because right now it is in the 'Advanced' section.

[kazupon]

Yeah, you're right.

The structure of docs in vue-i18n v9 is intentional. First of all, the docs are also written on a legacy basis to make it easier to migrate from v8.x to v9.

Vue.js docs also currently have the options API as the base docs and the composition API as another section. At some point, Vue.js will drop the Options API and focus on the Composition API.

That's when the vue-i18n v9 docs will be based on the Composition API.

[gagarine]

The problem with this approach it's then very confusing for people using vue-i18n and vuejs3 without a lot of prior knowledge of the legacy API. It's mostly written in reference of the old..

[matthew-white]

I think the new Vue 3 docs ~that are currently in progress~ speak to this conversation. The Composition API FAQ clarifies that Vue doesn't plan to deprecate the Options API. Because of that, the Vue Options API isn't slated to become a legacy API, so I think that it will be confusing to some that a Vue app that uses the Vue Options API will have to use a mode of Vue I18n called legacy mode.

[matthew-white]

I've been thinking more about this, and I believe that it's possible to use the Vue I18n Composition API in a component that uses the Vue Options API, and it's possible to use the Vue I18n Legacy API in a component that uses the Vue Composition API:

• The new Vue 3 docs describe how to use a composable like useI18n() in a component that uses the Options API: https://vuejs.org/guide/reusability/composables.html#using-composables-in-options-api (I haven't tried this myself)
• A component that uses the Vue Composition API can use the Vue I18n Legacy API by using the workaround I describe here: https://github.com/intlify/vue-i18n-next/discussions/605#discussioncomment-2057136

Mixing things in this way might not seem ideal, but I think it provides an interesting path forward for Vue I18n. It looks like the Vue Options API is here to stay, but Vue I18n might decide that it doesn't want to support two APIs for itself going forward (Legacy + Composition). One way to accomplish that would be to phase out the Legacy API. Components that use the Vue Options API could continue to use Vue I18n, by either specifying globalInjection: true or (especially if they use local scope) calling useI18n() within setup().

I also think it's important to support projects where some components use the Options API and some components use the Composition API. I believe that case will be somewhat common among large projects migrating from Vue 2 to Vue 3. I discuss that more in the discussion I linked to above. I think documenting the ways forward in that case would be very helpful.

Let me know if I can help with any of this! For example, I could help contribute documentation:

• Add guidance to the Vue I18n migration guide about what to do when some components use the Vue Options API and some components use the Vue Composition API
• Make it clear in the section about the Vue I18n Composition API that it's possible to use the Vue I18n Composition API with components that use the Vue Options API, including when local scope is used
• Briefly touch on the subject in the "Getting started" section. I think the Vue I18n Composition API could be recommended more strongly there if it's clear that components that use the Vue Options API can use the Vue I18n Composition API.

[kazupon]

@matthew-white Thank you for your comments! ❤️

Let me know if I can help with any of this! For example, I could help contribute documentation:

we are very happy to hear your comment that we can get support from you. :) We would hope you will improve the docs.