Skip to main content

Vue i18n : configuration complète de l'internationalisation avec vue-i18n

De l'installation à la production : configurez vue-i18n avec la Composition API, gérez les pluriels selon les règles CLDR, utilisez l'interpolation de composants et ajoutez des chaînes de repli de locale intelligentes.

1

Installer vue-i18n

vue-i18n est le plugin d'internationalisation officiel de Vue.js. Il fournit des traductions réactives, une pluralisation de type ICU, l'interpolation de composants, le formatage des dates, heures et nombres, ainsi que la prise en charge de l'Options API et de la Composition API.

Terminal
npm install vue-i18n@9
2

Configurer vue-i18n

Créez une instance i18n avec createI18n() et enregistrez-la en tant que plugin Vue. Définissez vos messages de locale, la locale par défaut, et configurez la locale de repli. vue-i18n prend en charge à la fois le mode legacy (Options API) et le mode 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 vous voyez des erreurs 'Not available in legacy mode', c'est que vous mélangez des appels i18n de la Composition API (useI18n()) avec une configuration en mode legacy. Définissez legacy: false dans createI18n() pour utiliser le mode Composition API, ou utilisez systématiquement la syntaxe $t() de l'Options API.
3

Utiliser les traductions dans les modèles

vue-i18n fournit la fonction $t() dans les modèles (Options API) et la fonction t() issue de useI18n() (Composition API). Les deux acceptent la clé de traduction ainsi que des paramètres nommés ou de liste facultatifs pour l'interpolation.

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

Gérer la pluralisation

vue-i18n prend en charge la pluralisation via des formes séparées par des barres verticales et la fonction $tc() (legacy) ou t() avec un paramètre count (Composition API). Définissez les formes plurielles dans vos messages de locale à l'aide du séparateur barre verticale : '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 syntaxe plurielle à barres verticales ne prend en charge que les pluriels cardinaux avec jusqu'à trois formes (zero | one | other). Pour les langues aux règles plurielles CLDR complexes (arabe, russe, polonais), utilisez la syntaxe ICU MessageFormat ou le modificateur @.plural avec des correspondances explicites de catégories CLDR.
5

Ajouter des chaînes de repli de locale

Le paramètre fallbackLocale intégré de vue-i18n ne prend en charge qu'une liste plate de locales de repli, et non des chaînes propres à chaque locale. Un utilisateur pt-BR ayant une clé manquante se replie sur l'anglais au lieu de pt-PT. vue-i18n-locale-chain ajoute des chaînes de fusion profonde configurables afin que les utilisateurs régionaux voient toujours la traduction disponible la plus proche.

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 fusionne les messages en profondeur au chargement. L'ensemble de messages fusionné est mis en cache par le système de réactivité de vue-i18n, il n'y a donc aucune pénalité de performance à l'exécution pour les recherches de repli.
6

Automatiser les traductions

Une fois vue-i18n configuré, traduisez vos fichiers JSON de langue à l'aide de l'IA. Depuis votre IDE, demandez à votre assistant IA de traduire le fichier source, ou intégrez la traduction à votre pipeline CI/CD pour une localisation entièrement automatisée.

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

Configuration de la chaîne de repli des locales

Configurez des chaînes de repli par locale afin que les utilisateurs régionaux voient la traduction disponible la plus proche, au lieu de basculer directement vers l'anglais. vue-i18n prend en charge un fallbackLocale de type objet pour définir des chaînes par locale.

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'objet fallbackLocale vous permet de définir des chaînes différentes pour différentes locales. Un utilisateur pt-BR se replie sur pt puis en, tandis qu'un utilisateur zh-Hant-TW se replie sur zh-Hant, zh, puis en.

Pièges courants

Mélange des modes Legacy et Composition API

Utiliser useI18n() avec legacy: true (valeur par défaut) provoque des erreurs. Définissez legacy: false dans createI18n() si vous utilisez la Composition API, ou limitez-vous à $t() dans les modèles avec l'Options API. Ne mélangez pas les deux modes au sein d'une même application.

Utilisation de v-html pour les chaînes traduites

Utiliser v-html pour afficher des traductions contenant du HTML présente un risque XSS si une valeur d'interpolation provient d'une saisie utilisateur. Utilisez le composant &lt;i18n-t&gt; pour les traductions comportant du HTML ou des composants Vue intégrés : il est sûr par défaut et prend en charge l'intégration réactive de composants.

Les utilisateurs régionaux voient l'anglais au lieu de la locale parente

Le fallbackLocale de vue-i18n est une liste plate, et non une chaîne par locale. pt-BR se replie sur ce qui figure dans la liste (généralement 'en'), en ignorant totalement pt-PT. Utilisez vue-i18n-locale-chain pour ajouter un repli régional adapté, avec fusion profonde (deep-merge).

Essayez i18n Agent maintenant

Déposez votre fichier de traduction ici

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

ou cliquez pour parcourir

Langues cibles

Aucune inscription requiseEstimation instantanée

FAQ Vue i18n