{"id":12499,"library":"vue-i18n-composable","title":"vue-i18n-composable","description":"vue-i18n-composable is a library that brings the Composition API pattern for internationalization (i18n) to Vue 2.x applications, specifically integrating with the popular `vue-i18n` library. Its current stable version is `2.0.0`, released in July 2022, which introduced direct support for Vue 2.7 without requiring the `@vue/composition-api` plugin. Previous versions, such as `v1.0.0`, targeted Vue 2.5 and 2.6 and necessitated the `@vue/composition-api` plugin. The package does not adhere to a strict time-based release cadence, with major versions often tied to critical Vue lifecycle updates or feature enhancements. It differentiates itself by allowing developers to leverage modern `setup` functions and `useI18n` composables within Vue 2 projects, offering a forward-looking development experience without the need for a full migration to Vue 3. This is particularly useful for large legacy Vue 2 applications aiming to incrementally modernize their codebase, and it is an official part of the Intlify ecosystem, which also maintains `vue-i18n` itself.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/intlify/vue-i18n-composable","tags":["javascript","composition-api","i18n","internationalization","intlify","vue","vue-i18n","vue.js","typescript"],"install":[{"cmd":"npm install vue-i18n-composable","lang":"bash","label":"npm"},{"cmd":"yarn add vue-i18n-composable","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-i18n-composable","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, specifies Vue 2.x compatibility. v2.x of this package requires Vue >=2.7 <3.","package":"vue","optional":false},{"reason":"Core internationalization library that this package builds upon. Peer dependency >=8 <9.","package":"vue-i18n","optional":false},{"reason":"Required for Vue 2.5 - 2.6 compatibility to enable Composition API features. Not needed for Vue 2.7+.","package":"@vue/composition-api","optional":true}],"imports":[{"note":"Used to create the i18n instance. This library is ESM-first and ships types, so prefer `import` syntax.","wrong":"const { createI18n } = require('vue-i18n-composable')","symbol":"createI18n","correct":"import { createI18n } from 'vue-i18n-composable'"},{"note":"The primary composable for accessing i18n functionality within Vue components. It's a named export.","wrong":"import useI18n from 'vue-i18n-composable'","symbol":"useI18n","correct":"import { useI18n } from 'vue-i18n-composable'"},{"note":"For Vue 2.7+, `defineComponent` is imported directly from 'vue'. For Vue 2.5-2.6, it must be imported from '@vue/composition-api'.","wrong":"import { defineComponent } from '@vue/composition-api'","symbol":"defineComponent","correct":"import { defineComponent } from 'vue'"}],"quickstart":{"code":"import Vue from 'vue'\nimport { createI18n } from 'vue-i18n-composable'\nimport { defineComponent } from 'vue' // For Vue 2.7+\n\nconst i18n = createI18n({\n  locale: 'en',\n  messages: {\n    en: {\n      greeting: 'Hello from Composition API!',\n      language: 'English'\n    },\n    ja: {\n      greeting: 'コンポジションAPIからのこんにちは！',\n      language: '日本語'\n    }\n  }\n})\n\nconst App = defineComponent({\n  template: `\n    <div>\n      <h1>{{ t('greeting') }}</h1>\n      <p>Current Language: {{ t('language') }}</p>\n      <button @click=\"setLocale('ja')\">Switch to Japanese</button>\n      <button @click=\"setLocale('en')\">Switch to English</button>\n    </div>\n  `,\n  setup() {\n    const { t, locale } = useI18n()\n\n    const setLocale = (lang) => {\n      locale.value = lang\n    }\n\n    return {\n      t,\n      setLocale\n    }\n  }\n})\n\nconst app = new Vue({\n  render: h => h(App),\n  i18n\n})\n\napp.$mount('#app')","lang":"typescript","description":"Demonstrates initializing `vue-i18n-composable` with `createI18n` and using `useI18n` within a Vue 2.7 `defineComponent` setup function to display translated text and change locales dynamically."},"warnings":[{"fix":"For Vue 2.7+, upgrade to `vue-i18n-composable@2.x` and remove `@vue/composition-api`. For Vue 2.5-2.6, use `vue-i18n-composable@1.x` and install `@vue/composition-api`.","message":"Vue version compatibility changed between v1 and v2. v1.x supports Vue 2.5-2.6, requiring `@vue/composition-api`. v2.x supports Vue 2.7+, which has native Composition API support and does not require the plugin.","severity":"breaking","affected_versions":">=1.0.0 <2.0.0"},{"fix":"Run `npm i @vue/composition-api` and add `import VueCompositionAPI from '@vue/composition-api'; Vue.use(VueCompositionAPI);` to your `main.js` or entry file.","message":"When using `vue-i18n-composable` with Vue 2.5 or 2.6, you must explicitly install and `Vue.use()` the `@vue/composition-api` plugin before creating your Vue app.","severity":"gotcha","affected_versions":"<2.0.0"},{"fix":"Adjust your `defineComponent` import based on your specific Vue 2.x patch version: `import { defineComponent } from 'vue'` for 2.7+, and `import { defineComponent } from '@vue/composition-api'` for 2.5-2.6.","message":"The `defineComponent` import source varies based on your Vue 2.x version. For Vue 2.7+, it's imported from 'vue'. For Vue 2.5-2.6, it comes from '@vue/composition-api'.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For Vue 2.7+, use `const app = new Vue({ ... }); app.$mount('#app');`. The `createApp` utility is only relevant for Vue 2.5-2.6 when using `@vue/composition-api`.","cause":"Attempting to use `createApp` from `@vue/composition-api` for mounting a Vue 2.7+ application without correctly initializing Vue.","error":"Cannot read properties of undefined (reading 'mount')"},{"fix":"Ensure `useI18n()` is called within a `setup` function and that the `i18n` instance created by `createI18n` is passed to the root Vue instance configuration (`new Vue({ i18n, ... })`).","cause":"The `useI18n()` composable was called outside of a Vue component's `setup` function or an equivalent Composition API context, or the `i18n` instance was not properly provided to the Vue app.","error":"TypeError: Cannot read properties of undefined (reading 't')"},{"fix":"Ensure the `createI18n` function receives an options object with at least an empty `messages` property, e.g., `createI18n({ locale: 'en', messages: {} })`.","cause":"The `messages` property, which defines the translation dictionary, was not provided in the options object passed to `createI18n`.","error":"Error: [vue-i18n] 'messages' property is missing in 'createI18n' options."}],"ecosystem":"npm"}