Changements cassants dans la version 9

La plupart des API proposées dans Vue I18n v9 (pour Vue 3) cherchent à maintenir la compatibilité, afin de faciliter la migration depuis v8 (pour Vue 2). Mais il y a encore quelques changements cassants que vous pourriez rencontrer lors de la migration de votre application. Ce guide explique comment adapter votre application pour qu'elle fonctionne avec Vue I18n v9.

APIs

`new VueI18n` devient `createI18n`

Vue I18n n'est plus une classe mais un ensemble de fonctions. Au lieu d'écrire new VueI18n(), vous devez maintenant appeler createI18n :

Vue I18n v8.x :

import Vue from 'vue'
import VueI18n from 'vue-i18n'

Vue.use(VueI18n)

const i18n = new VueI18n({
  // ...
})

new Vue({
  i18n,
  // ...
})

Vue I18n v9 ou ultérieure :

import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'

const i18n = createI18n({
  // ...
})

const app = createApp({
  // ...
})
app.use(i18n)

Raison : Changements de l'API globale de Vue 3 Global API changes, et changements d'architecture de l'API de Vue 3 liés aux instances de composants.

Renommage en `datetimeFormats` à partir de `dateTimeFormats`

Vue I18n v8.x :

const i18n = new VueI18n({
  // ...
  dateTimeFormats: {
    // ...
  }
})

Vue I18n v9 ou ultérieur :

const i18n = createI18n({
  // ...
  datetimeFormats: {
    // ...
  }
})

Valeur de retour de l'API de traduction

L'API de traduction comme $t et la fonction t ne retournent que des chaînes de caractères. Les valeurs d'objet et de tableau ne sont plus retournées.

Vue I18n v8.x :

// e.g. Local message structure as array
const i18n = new VueI18n({
  messages: {
    en: {
      errors: [
        'argument invalide',
        // ...
        'erreurs inattendues'
      ]
    }
  }
})

// e.g. Error component
const ErrorMessage = {
  props: {
    code: {
      type: Number,
      required: true
    }
  },
  template: `<p class="error">{{ getErrorMessage(code) }}</p>`,
  methods: {
    getErrorMessage(code) {
      return this.$t('errors')[code]
    }
  }
}

Dans Vue I18n v9 et ultérieur, cela a changé pour obtenir les messages locaux avec $tm / tm, et obtenir les messages locaux avec $rt ou rt. L'exemple suivant avec l'API Composition :

// e.g. Local message structure as array
const i18n = createI18n({
  messages: {
    en: {
      errors: [
        'argument invalide',
        // ...
        'erreurs inattendues'
      ]
    }
  }
})

// e.g. Error component
const ErrorMessage = {
  props: {
    code: {
      type: Number,
      required: true
    }
  },
  template: `<p class="error">{{ errors(code) }}</p>`,
  setup() {
    const { tm, rt } = useI18n()
    const errors = (code) => rt(tm('errors')[code])
    return { errors }
  }
}

Raison : Pour rendre l'obligation simple de retourner les résultats de traduction, et aussi pour supporter les types TypeScript.

Valeur de retour de l'API de pluriel

Similaire à Valeur de retour de l'API de traduction, l'API de pluriel comme $tc et tc ne retournent que des chaînes de caractères. Les valeurs d'objet et de tableau ne sont plus retournées.

Raison : Pour rendre l'obligation simple de retourner les résultats de traduction, et aussi pour supporter les types TypeScript.

Suppression de `getChoiceIndex`

CAUTION

Le code d'implémentation de l'option getChoiceIndex va être entièrement supprimé dans la version 10.

Pour personnaliser les règles de pluriel, Vue I18n v8.x étend getChoiceIndex de la classe VueI18n.

Vue I18n v8.x :

VueI18n.prototype.getChoiceIndex = function (choice, choicesLength) {
  // this === instance VueI18n, donc la propriété locale existe
  if (this.locale !== 'ru') {
    // procéder à l'implémentation par défaut
  }

  if (choice === 0) {
    return 0;
  }

  const teen = choice > 10 && choice < 20;
  const endsWithOne = choice % 10 === 1;

  if (!teen && endsWithOne) {
    return 1;
  }
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
    return 2;
  }
  return (choicesLength < 4) ? 2 : 3;
}

Dans Vue I18n v9 et ultérieur, vous pouvez le personnaliser avec les options suivantes :

Mode Legacy API :

import { createI18n } from 'vue-i18n'

function customRule(choice, choicesLength, orgRule) {
  if (choice === 0) {
    return 0
  }

  const teen = choice > 10 && choice < 20
  const endsWithOne = choice % 10 === 1
  if (!teen && endsWithOne) {
    return 1
  }
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
    return 2
  }

  return choicesLength < 4 ? 2 : 3
}

const i18n = createI18n({
  // ...
  pluralizationRules: {
    ru: customRule,
    // ...
  },
  // ...
})

Mode API Composition :

import { useI18n } from 'vue-i18n'

function customRule(choice, choicesLength, orgRule) {
  if (choice === 0) {
    return 0
  }

  const teen = choice > 10 && choice < 20
  const endsWithOne = choice % 10 === 1
  if (!teen && endsWithOne) {
    return 1
  }
  if (!teen && choice % 10 >= 2 && choice % 10 <= 4) {
    return 2
  }

  return choicesLength < 4 ? 2 : 3
}

const MyComp = {
  setup() {
    const { t } = useI18n({
      // ...
      pluralRules: {
        ru: customRule,
        // ...
      },
      // ...
    })

    // ...
  }
}

Raison : La classe VueI18n a été supprimée.

Modification de la valeur par défaut de l'option `warnHtmlInMessage`

Dans Vue I18n v8.x, la valeur de warnHtmlInMessage était "off". Par conséquent, par défaut, aucune alerte n'est affichée dans la console même si le message contient du HTML.

Dans Vue I18n v9 et ultérieur, les valeurs par défaut ont été modifiées comme suit :

Mode Legacy API : propriété warnHtmlInMessage : "warn"
Mode API Composition : propriété booléenne warnHtmlMessage, par défaut true

En mode développement, sauf si vous modifiez cette valeur, vous recevrez l'alerte dans la console par défaut.

En mode production, il ne détecte pas si le message contient du HTML pour maximiser les performances.

Raison : pour renforcer la sécurité des messages locaux

Informations sur la version

Les informations sur la version sont désormais accessibles via la syntaxe d'importation plutôt que via la propriété statique de la classe VueI18n.

Vue I18n v8.x :

import VueI18n from 'vue-i18n'

console.log(VueI18n.version)

Vue I18n v9 ou ultérieur :

import { VERSION } from 'vue-i18n'

console.log(VERSION)

Raison : Optimisation par tree shaking, et la classe VueI18n a été supprimée.

Suppression de l'availability Intl

Supprimé car les principaux navigateurs prennent maintenant en charge l'API d'internationalisation ECMAScript.

Vue I18n v8.x :

import VueI18n from 'vue-i18n'

console.log(VueI18n.availability)

Raison : Fin de vie d'IE9, et la classe VueI18n a été supprimée.

Suppression du formateur personnalisé

CAUTION

Le code d'implémentation de l'option formatter sera entièrement supprimé dans la version 10. En guise d'alternative, vue-i18n dispose du format de message personnalisé comme fonctionnalité expérimentale.

Raison : Difficile de fournir des formats personnalisés avec les nouvelles API de compilation et d'exécution. Nous prévoyons de le supporter dans la prochaine version majeure pour les prendre en charge dans ces API. Si vous souhaitez utiliser le format de message ICU, vous pouvez utiliser @formatjs/vue-intl

Suppression de l'option `preserveDirectiveContent`

CAUTION

Le code d'implémentation de l'option preserveDirectiveContent sera entièrement supprimé dans la version 10.

La directive v-t pour Vue 3 conserve maintenant le contenu par défaut. Par conséquent, cette option et ses propriétés ont été supprimées de l'instance VueI18n.

Vue I18n v8.x :

import VueI18n from 'vue-i18n'

const i18n = new VueI18n({
  // ...
  preserveDirectiveContent: true,
  // ...
})

Raison : Conserver le contenu de l'élément avec la directive v-t

Syntaxe du format de message

Suppression de l'objet semblable à un tableau pour l'interpolation de liste

Dans Vue I18n v8.x, l'interpolation de liste pouvait utiliser un objet semblable à un tableau comme paramètre, comme ceci :

import VueI18n from 'vue-i18n'

const i18n = new VueI18n({
  // ...
  messages: {
    en: {
      greeting: 'bonjour, {0} !'
    }
  },
  // ...
})

html

<p>{{ $t('greeting', { '0': 'kazupon' }) }}</p>

Dans Vue I18n v9 et ultérieur, vous ne pouvez plus utiliser des objets semblables à des tableaux pour l'interpolation de liste, vous devez utiliser un tableau :

html

<p>{{ $t('greeting', ['kazupon']) }}</p>

Raison : Fournir une API de traduction avec une interface d'argument cohérente

Gestion des caractères spéciaux

Les messages qui peuvent être traduits par Vue I18n peuvent être très traduits en utilisant la syntaxe de format de message, comme ceci :

txt

@.caml:{'pas de pommes'} | {0} pomme | {n} pommes

La syntaxe de format de message peut être exprimée en utilisant les caractères spéciaux suivants qui sont utilisés :

{, }, @, $, |

Depuis Vue I18n v9 et ultérieur, la syntaxe de format de message est maintenant gérée par le compilateur de format de message. Si vous utilisez ces caractères spéciaux dans un message, celui-ci produira une erreur lors de la compilation. Si vous voulez utiliser ces caractères spéciaux, vous devez utiliser l'interpolation littérale.

txt

// e.g. email address use case
{emailIdentity}{'@'}{emailDomain}

Raison : Pour permettre au compilateur de format de message de gérer correctement les caractères spéciaux de la syntaxe utilisée dans la syntaxe de format de message, il est nécessaire de les restreindre.

Suppression du groupement avec parenthèses pour les messages liés

Dans Vue I18n v8.x, la distinction était faite entre les références de clés dans les messages liés et les messages utilisant des parenthèses () pour les distinguer.

Vue I18n v8.x :

const messages = {
  en: {
    message: {
      dio: 'DIO',
      linked: 'Il y a une raison, tu as perdu, @:(message.dio).'
    }
  }
}

Dans Vue I18n v9 et ultérieur, les parenthèses ne sont plus nécessaires car le compilateur de format de message permet de gérer les interpolations nommées, de liste et littérales.

Vue I18n v9 ou ultérieur :

const messages = {
  en: {
    message: {
      dio: 'DIO',
      linked: "Il y a une raison, tu as perdu, @:{'message.dio'}."
    }
  }
}

Directive `v-t`

Suppression du modificateur `preserve`

CAUTION

Le code d'implémentation du modificateur preserve sera entièrement supprimé dans la version 10.

Similaire à Suppression de l'option preserveDirectiveContent, la directive v-t pour Vue 3 conserve maintenant le contenu par défaut. Par conséquent, le modificateur preserve a été supprimé de la directive v-t.

Vue I18n v8.x :

html

<p v-t.preserve="'bonjour'"></p>

Raison : Conserver le contenu de l'élément avec la directive v-t

API Composition

`useI18n` est maintenant une fonction

Dans Vue I18n v8.x, useI18n était une fonction de classe, vous deviez instancier avec new.

Vue I18n v8.x :

import { useI18n } from 'vue-i18n'

const i18n = new useI18n({ /* ... */ })

Dans Vue I18n v9 et ultérieur, useI18n est une fonction, vous pouvez l'utiliser directement.

Vue I18n v9 ou ultérieure :

import { useI18n } from 'vue-i18n'

const { t, i18n } = useI18n({ /* ... */ })

Raison : Pour permettre l'utilisation de useI18n dans le mode Composition API de Vue 3.

La propriété `tag` est optionnelle

Dans Vue I18n v8.x, la propriété tag pouvait être utilisée pour afficher les éléments enfants sans l'élément racine en spécifiant un nom de balise et la valeur booléenne false.

Vue I18n v8.x :

html

<i18n :tag="false" path="message.greeting">
  <span>bonjour !</span>
</i18n>

Depuis Vue I18n v9 ou ultérieur, vous pouvez faire la même chose en omettant la propriété tag.

Vue I18n v9 ou ultérieur :

html

<i18n-t keypath="message.greeting">
  <span>bonjour !</span>
</i18n-t>

Raison : Puisque Vue 3 prend maintenant en charge les Fragments Vue I18n v8.x :

html

<i18n path="message.greeting" />

Vue I18n v9 ou ultérieur :

html

<i18n-t keypath="message.greeting" />

Suppression de la syntaxe place avec l'attribut `place` et la propriété `places`

Dans Vue I18n v9 et ultérieur, l'attribut place et la propriété places ont été supprimés de l'interpolation des composants.

Vue I18n v8.x :

html

<i18n path="info" tag="p" :places="{ limit: refundLimit }">
  <span place="limit">{{ refundLimit }}</span>
  <a place="action" :href="refundUrl">{{ $t('refund') }}</a>
</i18n>

Vue I18n v9 ou ultérieur :

html

<i18n-t keypath="info" tag="p">
  <template #limit>
    <span>{{ refundLimit }}</span>
  <template>
  <template #action>
    <a :href="refundUrl">{{ $t('refund') }}</a>
  <template>
</i18n-t>

Raison : Il est maintenant possible de faire la même chose avec les slots

Composant NumberFormat

La propriété `tag` est optionnelle

Similaire à la section sur le composant de traduction, dans le composant NumberFormat (appelé composant fonctionnel i18n-n dans Vue I18n v8.x), la propriété tag pouvait être utilisée pour afficher les éléments enfants sans l'élément racine en spécifiant un nom de balise et la valeur booléenne false.

Vue I18n v8.x :

html

<i18n-n :tag="false" :value="100" format="currency">
  <span v-slot:integer="slotProps" styles="font-weight: bold">{{ slotProps.integer }}</span>
</i18n-n>

Depuis Vue I18n v9 ou ultérieur, vous pouvez faire la même chose en omettant la propriété tag.

Vue I18n v9 ou ultérieure :

html

<i18n-n :value="100" format="currency">
  <span v-slot:integer="slotProps" styles="font-weight: bold">{{ slotProps.integer }}</span>
</i18n-n>

Raison : Puisque Vue 3 prend maintenant en charge les Fragments

general

Variables

Functions

Interfaces

Type Aliases

vue

Interfaces

Changements cassants dans la version 9

APIs

`new VueI18n` devient `createI18n`

Renommage en `datetimeFormats` à partir de `dateTimeFormats`

Valeur de retour de l'API de traduction

Valeur de retour de l'API de pluriel

Suppression de `getChoiceIndex`

Modification de la valeur par défaut de l'option `warnHtmlInMessage`

Informations sur la version

Suppression de l'availability Intl

Suppression du formateur personnalisé

Suppression de l'option `preserveDirectiveContent`

Syntaxe du format de message

Suppression de l'objet semblable à un tableau pour l'interpolation de liste

Gestion des caractères spéciaux

Suppression du groupement avec parenthèses pour les messages liés

Directive `v-t`

Suppression du modificateur `preserve`

API Composition

`useI18n` est maintenant une fonction

La propriété `tag` est optionnelle

Suppression de la syntaxe place avec l'attribut `place` et la propriété `places`

Composant NumberFormat

La propriété `tag` est optionnelle

Changements cassants dans la version 9 ​

APIs ​

new VueI18n devient createI18n ​

Renommage en datetimeFormats à partir de dateTimeFormats ​

Valeur de retour de l'API de traduction ​

Valeur de retour de l'API de pluriel ​

Suppression de getChoiceIndex ​

Modification de la valeur par défaut de l'option warnHtmlInMessage ​

Informations sur la version ​

Suppression de l'availability Intl ​

Suppression du formateur personnalisé ​

Suppression de l'option preserveDirectiveContent ​

Syntaxe du format de message ​

Suppression de l'objet semblable à un tableau pour l'interpolation de liste ​

Gestion des caractères spéciaux ​

Suppression du groupement avec parenthèses pour les messages liés ​

Directive v-t ​

Suppression du modificateur preserve ​

API Composition ​

useI18n est maintenant une fonction ​

La propriété tag est optionnelle ​

Suppression de la syntaxe place avec l'attribut place et la propriété places ​

Composant NumberFormat ​

La propriété tag est optionnelle ​

Changements cassants dans la version 9

APIs

`new VueI18n` devient `createI18n`

Renommage en `datetimeFormats` à partir de `dateTimeFormats`

Valeur de retour de l'API de traduction

Valeur de retour de l'API de pluriel

Suppression de `getChoiceIndex`

Modification de la valeur par défaut de l'option `warnHtmlInMessage`

Informations sur la version

Suppression de l'availability Intl

Suppression du formateur personnalisé

Suppression de l'option `preserveDirectiveContent`

Syntaxe du format de message

Suppression de l'objet semblable à un tableau pour l'interpolation de liste

Gestion des caractères spéciaux

Suppression du groupement avec parenthèses pour les messages liés

Directive `v-t`

Suppression du modificateur `preserve`

API Composition

`useI18n` est maintenant une fonction

La propriété `tag` est optionnelle

Suppression de la syntaxe place avec l'attribut `place` et la propriété `places`

Composant NumberFormat

La propriété `tag` est optionnelle