Skip to main content

i18n en Vue: configuración completa con vue-i18n

De la instalación a producción: configure vue-i18n con Composition API, gestione la pluralización con reglas CLDR, use interpolación de componentes y añada cadenas inteligentes de respaldo regional.

1

Instalar vue-i18n

vue-i18n es el plugin oficial de internacionalización para Vue.js. Ofrece traducciones reactivas, pluralización al estilo ICU, interpolación de componentes, formato de fechas y números, y compatibilidad con Options API y Composition API.

Terminal
npm install vue-i18n@9
2

Configurar vue-i18n

Cree una instancia con createI18n() y regístrela como plugin de Vue. Defina los mensajes, la región predeterminada y la de respaldo. vue-i18n admite los modos legacy —Options API— y composition —Composition API—.

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'
import en from './locales/en.json'
import de from './locales/de.json'

const i18n = createI18n({
  legacy: false,           // Use Composition API mode
  locale: 'en',            // Default locale
  fallbackLocale: 'en',   // Fallback locale
  messages: { en, de },
})

export default i18n
src/main.ts
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import i18n from './i18n'

const app = createApp(App)
app.use(i18n)
app.mount('#app')
Si ve errores 'Not available in legacy mode', está mezclando llamadas de Composition API —useI18n()— con el modo heredado. Defina legacy: false en createI18n() o utilice de forma coherente la sintaxis $t() de Options API.
3

Utilizar traducciones en plantillas

vue-i18n ofrece $t() en plantillas —Options API— y t() desde useI18n() —Composition API—. Ambas aceptan la clave y parámetros con nombre o lista opcionales para interpolar.

src/locales/en.json
// src/locales/en.json
{
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "greeting": "Hello, {name}!",
  "cart": {
    "itemCount": "no items | one item | {count} items"
  }
}

// src/locales/de.json
{
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "greeting": "Hallo, {name}!",
  "cart": {
    "itemCount": "keine Artikel | ein Artikel | {count} Artikel"
  }
}
4

Gestionar la pluralización

vue-i18n admite pluralización mediante formas separadas por barras y $tc() —heredado— o t() con count —Composition API—. Defina las formas en los mensajes: 'no items | one item | {count} items'.

MyComponent.vue
<template>
  <div>
    <!-- Simple translation -->
    <h1>{{ $t('nav.home') }}</h1>

    <!-- With variables -->
    <p>{{ $t('greeting', { name: userName }) }}</p>

    <!-- In attributes -->
    <input :placeholder="$t('nav.settings')" />

    <!-- Composition API -->
    <p>{{ greeting }}</p>
  </div>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { t } = useI18n()
const userName = 'Alice'
const greeting = t('greeting', { name: userName })
</script>
La sintaxis con barras solo admite plurales cardinales de hasta tres formas —zero, one y other—. Para reglas CLDR complejas —árabe, ruso o polaco—, use ICU MessageFormat o el modificador @.plural con asociaciones explícitas de categorías.
5

Añadir cadenas de respaldo regional

fallbackLocale integrado en vue-i18n solo admite una lista plana, no cadenas por configuración regional. Un usuario pt-BR con una clave ausente pasa al inglés en vez de pt-PT. vue-i18n-locale-chain añade cadenas configurables con combinación en profundidad para mostrar siempre la traducción más próxima.

Plurals.vue
<template>
  <div>
    <!-- Pipe-separated plurals -->
    <p>{{ $t('cart.itemCount', count) }}</p>

    <!-- Named plurals (recommended for complex languages) -->
    <p>{{ $t('orders', { n: orderCount }) }}</p>
  </div>
</template>

<!-- In your locale file: -->
<!-- "orders": "{n} order | {n} orders" -->
vue-i18n-locale-chain combina mensajes durante la carga. El sistema reactivo de vue-i18n almacena el resultado en caché, por lo que no hay penalización durante las búsquedas.
6

Automatizar traducciones

Cuando configure vue-i18n, traduzca sus JSON regionales con IA. Desde el IDE, pida a su asistente que traduzca el origen o integre la traducción en CI/CD para automatizar por completo la localización.

LanguageSwitcher.vue
<template>
  <select v-model="locale">
    <option v-for="lang in availableLocales" :key="lang" :value="lang">
      {{ lang }}
    </option>
  </select>
</template>

<script setup lang="ts">
import { useI18n } from 'vue-i18n'

const { locale, availableLocales } = useI18n()
</script>
src/i18n.ts (lazy loading)
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  fallbackLocale: 'en',
  messages: {},
})

export async function loadLocale(locale: string) {
  const messages = await import(`./locales/${locale}.json`)
  i18n.global.setLocaleMessage(locale, messages.default)
  i18n.global.locale.value = locale
}

export default i18n
7

Configuración de cadenas de respaldo regional

Configure cadenas por configuración regional para que los usuarios vean la traducción disponible más próxima en vez de pasar al inglés. vue-i18n admite fallbackLocale como objeto para definirlas.

src/i18n.ts
// src/i18n.ts
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  legacy: false,
  locale: 'pt-BR',
  fallbackLocale: {
    'pt-BR': ['pt', 'en'],
    'zh-Hant-TW': ['zh-Hant', 'zh', 'en'],
    'es-419': ['es', 'en'],
    default: ['en'],
  },
  messages: {
    en: { /* ... */ },
    pt: { /* ... */ },
    'pt-BR': { /* ... */ },
  },
})
El objeto fallbackLocale permite cadenas distintas por región. Un usuario pt-BR recurre a pt y luego en, mientras zh-Hant-TW recurre a zh-Hant, zh y en.

Errores habituales

Mezclar los modos heredado y Composition API

Utilizar useI18n() con legacy: true —valor predeterminado— provoca errores. Defina legacy: false si usa Composition API o mantenga $t() en plantillas con Options API. No mezcle ambos modos.

Utilizar v-html para cadenas traducidas

Renderizar traducciones con HTML mediante v-html conlleva riesgo de XSS si algún valor procede del usuario. Utilice &lt;i18n-t&gt; para traducciones con HTML o componentes Vue: es seguro de forma predeterminada y admite inserción reactiva.

Los usuarios regionales ven inglés en vez de la configuración principal

fallbackLocale de vue-i18n es una lista plana, no una cadena por región. pt-BR recurre a lo que figure en ella —normalmente 'en'— y omite pt-PT. Utilice vue-i18n-locale-chain para añadir respaldo regional con combinación en profundidad.

Pruebe i18n Agent ahora

Arrastre y suelte aquí su archivo de traducción

JSON, YAML, PO, XML, CSV, Markdown, Properties

o haga clic para seleccionar

Idiomas de destino

No es necesario registrarsePresupuesto al instante

Preguntas frecuentes sobre i18n en Vue