Getting started

Creating a global application with Vue + Vue I18n is dead simple. With Vue.js, we are already composing our application with components. When adding Vue I18n to the mix, all we need to do is ready resource messages and simply use the localization API that are offered with Vue I18n.

NOTE

This guide will assume that you are already familiar with Vue itself. You don't need to be a Vue expert, but you may occasionally need to refer back to the core Vue documentation for more information about certain features.

An example

we're going to consider this example:

• StackBlitz example

Let's start by looking at the root component, App.vue.

App.vue

<script setup>
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
</script>

<template>
  <h1>{{ t('message.hello') }}</h1>
</template>

In the template, we use the t function from useI18n() to localize. This allows Vue I18n to change the locale without rewriting the template, and to support the globally application.

You will have the following output:

<h1>こんにちは、世界</h1>

Let's take a look at how this is achieved in JavaScript!

Creating the i18n instance

The i18n instance is created by calling the function createI18n.

const i18n = createI18n({
  locale: 'ja',
  fallbackLocale: 'en',
  messages: {
    en: {
      message: {
        hello: 'hello world'
      }
    },
    ja: {
      message: {
        hello: 'こんにちは、世界'
      }
    }
  }
})

We can specify some options to createI18n. The important options are the locale, fallbackLocale, and messages options.

locale is the language of the Vue application to be localized.

fallbackLocale is the language to fall back to if the key resource specified in the translation API (such as t from useI18n()) is not found in the language of locale.

messages is the locale messages to translate with the translation API. The structure of the locale message is the hierarchical object structure with each locale as the top property

Registering the i18n plugin

Once we've created our i18n instance, we need to register it as a plugin by calling use on our application:

const app = createApp(Vue)
app.use(i18n)
app.mount('#app')

Like with most Vue plugins, the call to use needs to happen before the call to mount.

If you're curious about what this plugin does, some of its responsibilities include:

1. Adding the global properties and methods such as $t, $i18n
2. Enabling the useI18n composables
3. Globally registering the i18n-t, i18n-d, and i18n-n components.

Conventions in this guide

Single-File Components

Vue I18n is most commonly used in applications built using a bundler (e.g. Vite) and SFCs (i.e. .vue files). Most of the examples in this guide will be written in that style, but Vue I18n itself doesn't require you to use build tools or SFCs.

For example, if you're using the global builds of Vue and Vue I18n, the libraries are exposed via global objects, rather than imports:

const { createApp } = Vue
const { createI18n, useI18n } = VueI18n

Component API style

Vue I18n v12 uses the Composition API exclusively. Examples in this guide will typically use <script setup>, rather than an explicit setup function.

If you need a refresher about Vue's Composition API, see Vue - API Styles.

In templates, you can use t() returned from useI18n(), or use $t which is globally injected by default (via globalInjection: true).

NOTE

If you are using Vue I18n v11 or earlier with Legacy API mode, see the v11 Guide.