Vue I18n

11.3.2 · active · verified Wed Apr 22

Vue I18n is the official and widely adopted internationalization plugin for Vue.js, providing comprehensive features to localize Vue 3 applications. The current stable version is 11.3.2, with the project maintaining an active and frequent release cadence focused on bug fixes and incremental feature enhancements, as evidenced by its recent rapid succession of patch releases. Key differentiators include its deep and seamless integration with Vue's reactivity system, support for both the Options API and Composition API, sophisticated pluralization rules, robust date and number formatting capabilities, and a flexible message syntax that handles interpolation, linked messages, and even HTML content. It provides various optimized build artifacts (e.g., global, esm-browser, esm-bundler, cjs, node.mjs) to cater to diverse deployment environments, from direct CDN usage in browsers to modern bundler-driven setups and server-side rendering with Node.js. It's built on the Intlify project, ensuring a consistent and performant i18n experience for the Vue ecosystem.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates the setup of Vue I18n with Vue 3's Composition API, including creating an i18n instance, defining messages, using the `t` function for translations, and dynamically changing the locale.

import { createApp, ref } from 'vue'
import { createI18n, useI18n } from 'vue-i18n'

// Root Vue app component (e.g., App.vue)
const App = {
  template: `
    <div>
      <h1>{{ t('greeting', { name: 'World' }) }}</h1>
      <p>{{ t('welcome') }}</p>
      <p>{{ t('pluralExample', { count: messageCount }) }}</p>
      <p>{{ t('dynamicMessage', { type: 'dynamic' }) }}</p>

      <button @click="changeLocale('en')">English</button>
      <button @click="changeLocale('fr')">Français</button>
    </div>
  `,
  setup() {
    // Use the Composition API hook
    const { t, locale } = useI18n({ useScope: 'global' }) // 'global' scope is necessary for root app messages

    const messageCount = ref(1)

    const changeLocale = (lang: string) => {
      locale.value = lang // Reactively change the current locale
      messageCount.value = lang === 'en' ? 5 : 1 // Example for pluralization demo
    }

    return { t, messageCount, changeLocale }
  }
}

// Locale messages definitions
const messages = {
  en: {
    greeting: 'Hello, {name}!',
    welcome: 'Welcome to our site.',
    pluralExample: 'You have {count} message | You have {count} messages.',
    dynamicMessage: 'This is a {type} message.'
  },
  fr: {
    greeting: 'Bonjour, {name} !',
    welcome: 'Bienvenue sur notre site.',
    pluralExample: 'Vous avez {count} message | Vous avez {count} messages.',
    dynamicMessage: 'Ceci est un message {type}.'
  }
}

// Create the i18n instance
const i18n = createI18n({
  legacy: false, // Essential for using Composition API with Vue I18n v9+
  locale: 'en', // Default locale
  fallbackLocale: 'en', // Fallback locale if a message is not found
  messages // Provide all locale messages
})

// Create the Vue app instance
const app = createApp(App)

// Install the i18n plugin
app.use(i18n)

// Mount the app to a DOM element
app.mount('#app')

view raw JSON →