Using composition with legacy in local scopes

[daniesg]

It looks like the composition API doesn't work well with legacy when it comes to locale scopes. I have an app where I generally want i18n enabled everywhere with local scopes. So it's common to see a component look like this:

import messages from '../ path to locales/ thing.js';

export default {
  ...
  i18n: { messages }
  ...
}

There are a few places where I actually want to use the composition API. Essentially I have a composition function that does some common work and needs it's own translations. About 4-5 components use this composition function.

So the composition function looks like this:

import messages from '../.locales for this function.js';
import { useI18n } from 'vue-i18n';
import { computed, ref } from 'vue';

export default function(options = {}) {
  const { t } = useI18n({ messages });
  ... // do some work and return translations

And the component that uses this function looks like this:

  import messages from "../locales for this component.js";
  import { mapState } from 'vuex';
  import { ref, computed } from 'vue';
  import myCompositionFunction from '../my-composition-function.js';

  export default {
    ...
    i18n: { messages },
    setup: function() {
      let thing = myCompositionFunction('stuff');
      ...
    },
    ...
  }

My global setup looks like this:

  const i18n = createI18n({
    locale: 'en',
    fallbackLocale: 'en',
    messages,
    silentFallbackWarn: true,
    silentTranslationWarn: true,
    legacy: false,
    globalInjection: true
  });

I'm not sure if this is a feature request or bug, but shouldn't this work? Because it definitely doesn't. Now the only translations I can see are global translations in all of my components. Even the components that don't use/have a setup function. Is this a use case not supported or am I doing something wrong.

Module versions:

• vue: 3.0.9
• vue-i18n: 9.0.0

[kazupon]

Thank you for your feedback!

Unfortunately, in vue-i18n v9, it is not possible to support i18n in Vue applications using both Composition API Style and Legacy API Style at the same time.

This is the intention of vue-i18n v9.
You should unify your API code usage style to one of them.

Several of the reasons for the restriction are as follows:

• To ensure maintainability of i18n support in Vue applications:
  • Code that mixes Composition API Style and Legacy API Style will be chaotic.
• To make it easier to support the Option Style API in Vue.js when it is dropped in the future
  • Legacy API is vue-i18n's API for the Option Style API, and vue-i18n is planning to drop Legacy API as well as Vue.
• Architectural limitations of vue-i18n's i18n resource management:
  • it's scoped by global & local, and there is a mismatch between Composition API Style and Legacy API Style due to subtle differences.

[gagarine]

The doc is not really clear that vue-18n composition API mode and legacy API mode are not compatible.

[littleboarx]

if it's too difficult for you to move to composition API for an old project, I found a 'magic' way to be compatible with it: install two i18n instances that use different legacy options.
It's not perfect but it works well for me. I think there should be a more friendly way to be compatible with it when migrating old codes.
there is a code example:

const i18n = createI18n<true>({
    globalInjection: true,
    legacy: true as const,
    locale: 'en_EN', // set locale
    fallbackLocale: 'en_EN',
    messages: i18nMessage,
})

const i18nComposition = createI18n<false>({
    globalInjection: true,
    legacy: false as const,
    locale: 'en_EN', // set locale
    fallbackLocale: 'en_EN',
    messages: i18nMessage,
})
#####################
createApp(App)
    .use(router)
    .use(i18n)
    .use(i18nComposition)

[LaurentLord]

@kazupon
Using script setup, the only solution I found is using two instances of i18n as describe by @littleboarx.

Did you find any way to turn off the warnings about having i18n already registered?

[matthew-white]

I am running into a similar issue while migrating a large project from Vue 2 to Vue 3. Because there are so many existing components, most components will continue to use the Vue Options API, and the app will use the Vue I18n Legacy API: moving all components to the Composition API would make it much harder to migrate to Vue 3, which we want to do sooner rather than later.

However, we have run into an issue with the components that we have migrated to the Vue Composition API. There aren't many of these, but some components had to be migrated to the Composition API due to changes in Vue 3. (For example, a component that used this.$on('hook:beforeDestroy') in Vue 2 will use the Composition API and onBeforeUnmount() in Vue 3.) The issue is that these components use i18n custom blocks, but because the app uses the Vue I18n Legacy API, Vue I18n doesn't seem to provide access to those messages in setup(). There's no easy way to access this.$i18n in setup(), and useI18n() throws an error, so these existing components don't seem to have a way to access their messages.

The answer above seems to imply that if you have to migrate a single component to the Composition API, then you have to migrate them all. However, that would not be practical for our project.

In my opinion, it also doesn't seem consistent with Vue 3's approach to the Composition API, which is opt-in on the component level. While I know that some projects will find it easiest to only use the Options API or only use the Composition API, another strategy is to use the Options API for simple components and use the Composition API for complex components where grouping functionality by concern is especially useful. Our project will mostly continue to use the Options API, but like I said, some components will have to use the Composition API. We will probably also start experimenting with using the Composition API for new components, especially complex new components. Vue 3 seems to support this approach, as do other plugins, including Vue Router and Vuex. However, Vue I18n seems to require that all components use one or the other (at least if you are using local scope).

The answer above also seems to say that Vue plans to deprecate the Options API. While that may have been the case at one point, I don't believe that that's the plan right now: https://stackoverflow.com/questions/68611657/do-i-have-to-use-the-composition-api-in-vue-3-or-can-i-still-do-things-the-vue

I think that it would be very helpful for Vue I18n to provide a migration path for projects that use a mix of the Options API and the Vue Composition API. We are loving many other features of Vue I18n v9, but we have found this aspect of the migration to be a challenge.

At the moment, our plan for components that use setup() and have an i18n custom block is to access the i18n object using getCurrentInstance().ctx.$i18n. In setup(), $i18n won't initially be available on getCurrentInstance().ctx, but it does seem to be available within lifecycle hooks. (I think that's because the Vue I18n Legacy API defines $i18n in a beforeCreate hook.) That means that we can do something like the following:

export default {
  setup() {
    let i18n
    onBeforeMount(() => { i18n = getCurrentInstance().ctx.$i18n })
  }
}

This allows us to use the i18n object within any code that is run after the onBeforeMount() hook. In other words, this allows us to use the Vue I18n Legacy API within a component that uses setup().

[kazupon]

Thank you for detailed comments!

At the moment, our plan for components that use setup() and have an i18n custom block is to access the i18n object using getCurrentInstance().ctx.$i18n. In setup(), $i18n won't initially be available on getCurrentInstance().ctx, but it does seem to be available within lifecycle hooks. (I think that's because the Vue I18n Legacy API defines $i18n in a beforeCreate hook.) That means that we can do something like the following:

export default {
  setup() {
    let i18n
    onBeforeMount(() => { i18n = getCurrentInstance().ctx.$i18n })
  }
}

This allows us to use the i18n object within any code that is run after the onBeforeMount() hook. In other words, this allows us to use the Vue I18n Legacy API within a component that uses setup().

We might be able to provide Composition API for Vue I18n Legacy API only as Vue I18n official API, like the useI18nBridge.

I also recognize the importance of the transition from Vue 2 to Vue 3. That's why I've created packages like vue-i18n-bridge that work on Vue 2.
We would like to support the migration as much as possible :)

[kazupon]

And for ease of migration, I noticed that should be useI18n

[kazupon]

we will be able to use useI18n in Legacy API mode soon. but, there is a limitation that SSR cannot be supported. This is due to the architecture of legacy API mode.

#940

[kazupon]

I've just written migration docs
https://vue-i18n.intlify.dev/guide/migration/vue3.html

[Theiaz]

This post describes exactly the point where i stumbled on!