Skip to main content

I18n de Vue: configuració completa de la internacionalització amb vue-i18n

Des de la instal·lació fins a producció: configuri vue-i18n amb la Composition API, gestioni els plurals amb regles CLDR, utilitzi la interpolació de components i afegeixi cadenes intel·ligents de configuracions regionals de reserva.

1

Instal·lar vue-i18n

vue-i18n és el connector oficial d’internacionalització de Vue.js. Proporciona traduccions reactives, pluralització a l’estil d’ICU, interpolació de components, formatació de dates, hores i nombres i compatibilitat tant amb l’Options API com amb la Composition API.

Terminal
npm install vue-i18n@9
2

Configurar vue-i18n

Creï una instància d’i18n amb createI18n() i registri-la com a connector de Vue. Defineixi els missatges de les configuracions regionals, estableixi la configuració regional predeterminada i configuri'n la de reserva. vue-i18n admet tant el mode heretat (Options API) com el mode de composició (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 veu errors 'Not available in legacy mode', està combinant crides d’i18n de la Composition API (useI18n()) amb la configuració del mode heretat. Estableixi legacy: false a createI18n() per utilitzar el mode de la Composition API o faci servir sistemàticament la sintaxi $t() de l’Options API.
3

Utilitzar traduccions a les plantilles

vue-i18n proporciona la funció $t() a les plantilles (Options API) i la funció t() de useI18n() (Composition API). Totes dues accepten la clau de traducció i paràmetres opcionals amb nom o en forma de llista per a la interpolació.

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 pluralització

vue-i18n admet la pluralització mitjançant formes separades per barres verticals i la funció $tc() (mode heretat) o t() amb un paràmetre de quantitat (Composition API). Defineixi les formes plurals als missatges de configuració regional amb el separador de barra vertical: '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 sintaxi de plurals separats per barres verticals només admet plurals cardinals amb un màxim de tres formes (zero | one | other). Per als idiomes amb regles de plural CLDR complexes (àrab, rus o polonès), utilitzi la sintaxi ICU MessageFormat o el modificador @.plural amb assignacions explícites de categories CLDR.
5

Afegir cadenes de configuracions regionals de reserva

El fallbackLocale integrat de vue-i18n només admet una llista plana de configuracions regionals de reserva, no pas cadenes específiques per configuració regional. Un usuari de pt-BR que trobi una clau absent veurà el text en anglès en lloc del de pt-PT. vue-i18n-locale-chain afegeix cadenes configurables amb fusió en profunditat perquè els usuaris de variants regionals vegin sempre la traducció disponible més propera.

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 fusiona els missatges en profunditat durant la càrrega. El sistema de reactivitat de vue-i18n emmagatzema el conjunt de missatges fusionat a la memòria cau, de manera que les consultes de reserva no comporten cap penalització de rendiment durant l’execució.
6

Automatitzar les traduccions

Un cop configurat vue-i18n, tradueixi els fitxers JSON de configuració regional mitjançant IA. Des de l’IDE, demani a l’assistent d’IA que tradueixi el fitxer d’origen o integri la traducció al procés de CI/CD per automatitzar completament la localització.

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ó de les cadenes de configuracions regionals de reserva

Configuri cadenes de reserva específiques per configuració regional perquè els usuaris de variants regionals vegin la traducció disponible més propera en lloc de passar directament a l’anglès. vue-i18n admet fallbackLocale en forma d’objecte per definir cadenes per configuració regional.

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': { /* ... */ },
  },
})
L’objecte fallbackLocale permet definir cadenes diferents per a configuracions regionals diferents. Un usuari de pt-BR recorre a pt i després a en, mentre que un usuari de zh-Hant-TW recorre a zh-Hant, zh i, finalment, en.

Errors habituals

Combinar els modes heretat i de la Composition API

Utilitzar useI18n() amb legacy: true (el valor predeterminat) provoca errors. Estableixi legacy: false a createI18n() si utilitzi la Composition API o limiti's a $t() a les plantilles amb l’Options API. No combini tots dos modes a la mateixa aplicació.

Utilitzar v-html per a cadenes traduïdes

Utilitzar v-html per representar traduccions que contenen HTML comporta un risc d’XSS si algun valor d’interpolació prové de dades introduïdes per l’usuari. Utilitzi el component &lt;i18n-t&gt; per a traduccions amb HTML o components de Vue incrustats: és segur per defecte i admet la incrustació de components reactius.

Els usuaris de variants regionals veuen l’anglès en lloc de la configuració regional superior

El fallbackLocale de vue-i18n és una llista plana, no pas una cadena específica per configuració regional. pt-BR recorre al que hi hagi a la llista (normalment 'en') i omet completament pt-PT. Utilitzi vue-i18n-locale-chain per afegir un mecanisme de reserva regional adequat amb fusió en profunditat.

Provar i18n Agent ara

Arrossegar aquí el fitxer de traducció

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

o fer clic per explorar

Idiomes de destinació

No cal registrePressupost instantani

Preguntes freqüents sobre l’i18n de Vue