Comenzando

Crear una aplicación global con Vue + Vue I18n es muy sencillo. Con Vue.js, ya estamos creando nuestra aplicación con componentes. Al agregar Vue I18n, todo lo que necesitamos hacer es preparar los recursos de mensajes y simplemente usar la API de localización que ofrece Vue I18n.

NOTA

Esta guía asumirá que ya estás familiarizado con Vue en sí. No necesitas ser un experto en Vue, pero ocasionalmente podrías necesitar volver a la documentación principal de Vue para obtener más información sobre ciertas características.

Un ejemplo

Vamos a considerar este ejemplo:

• Ejemplo en StackBlitz

Comencemos mirando el componente raíz, App.vue.

App.vue

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

En la plantilla, usamos la API de traducción $t inyectada por Vue I18n, para localizar. Esto permite que Vue I18n cambie el idioma sin necesidad de reescribir la plantilla, además de permitir soportar la aplicación globalmente.

Tendrás la siguiente salida:

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

Veamos cómo se logra esto en JavaScript.

Creando la instancia i18n

La instancia i18n se crea llamando a la función createI18n.

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

Podemos especificar algunas opciones en createI18n. Las opciones importantes son las opciones locale, fallbackLocale y messages.

locale es el idioma de la aplicación Vue a localizar.

fallbackLocale es el idioma al que recurrir si la clave de recurso especificada en la API de traducción $t no se encuentra en el idioma de locale.

messages son los mensajes locales para traducir con la API de traducción $t. La estructura del mensaje local es una estructura de objeto jerárquico con cada idioma como propiedad superior.

Registrando el plugin i18n

Una vez que hayamos creado nuestra instancia i18n, necesitamos registrarla como un plugin llamando a use en nuestra aplicación:

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

Al igual que con la mayoría de plugins de Vue, la llamada a use debe realizarse antes de la llamada a mount.

Si te interesa saber qué hace este plugin, algunas de sus responsabilidades incluyen:

1. Añadir propiedades y métodos globales como $t, $i18n
2. Habilitar los componibles useI18n
3. Registrar globalmente los componentes i18n-t, i18n-d, y i18n-n.

Convenciones en esta guía

Componentes de Archivo Único

Vue I18n se utiliza comúnmente en aplicaciones construidas usando un empaquetador (por ejemplo, Vite) y SFCs (es decir, archivos .vue). La mayoría de los ejemplos en esta guía estarán escritos en ese estilo, aunque Vue I18n en sí no requiere usar herramientas de compilación ni SFCs.

Por ejemplo, si estás usando las versiones globales de Vue y Vue I18n, las bibliotecas están expuestas mediante objetos globales, en lugar de importaciones:

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

Estilo de la API de componentes

Vue I18n puede usarse tanto con la API de composición como con la API de opciones. Cuando sea relevante, los ejemplos en esta guía mostrarán componentes escritos en ambos estilos. Los ejemplos con la API de composición generalmente usarán <script setup>, en lugar de una función setup explícita.

Si necesitas repasar los dos estilos, consulta Vue - Estilos de API.

Vue I18n funciona tanto con la API de composición de Vue como con la API de opciones. Vue I18n tiene dos estilos de API como Vue, la API de composición y la API heredada para uso con la API de opciones.

IMPORTANTE

En Vue I18n v9 y posteriores, la API ofrecida por Vue I18n v8.x se denomina modo API Heredada. La API heredada está obsoleta en Vue I18n v11 y será eliminada en Vue I18n v12. Recomendamos usar el modo de API de composición.

Las siguientes secciones se explicarán utilizando la API heredada.

Si deseas usarlo en estilo de API de composición y ya comprendes Vue I18n, puedes saltar a aquí.