Syntaxe du format des messages

Vue I18n peut utiliser la syntaxe de format des messages pour localiser les messages à afficher dans l'interface utilisateur. Les messages de Vue I18n sont des interpolations et des messages avec diverses syntaxes de fonctionnalités.

Interpolations

Vue I18n prend en charge l'interpolation utilisant des espaces réservés {} comme "Mustache".

Interpolation nommée

L'interpolation nommée peut être interpolée dans l'espace réservé en utilisant les noms de variables définis en JavaScript.

Par exemple, la ressource de messages locaux suivante :

const messages = {
  en: {
    message: {
      hello: '{msg} world'
    }
  }
}

Les messages locaux sont la ressource spécifiée par l'option messages de createI18n. Elle définit la locale en avec { message: { hello: '{msg} world' } }.

L'interpolation nommée vous permet de spécifier les variables définies en JavaScript. Dans le message local ci-dessus, vous pouvez le localiser en donnant la variable msg définie en JavaScript comme paramètre à la fonction de traduction.

Le nom de variable à l'intérieur de {} doit commencer par une lettre (a-z, A-Z) ou un trait de soulignement (_), suivi de toute combinaison de lettres, chiffres, traits de soulignement (_), tirets (-), ou signes dollar ($).

Exemples : {msg}, {_userName}, {user-id}, {total$}

Voici un exemple d'utilisation de $t dans un template :

<p>{{ $t('message.hello', { msg: 'hello' }) }}</p>

Le premier argument est message.hello comme clé de messages locaux, et le deuxième argument est un objet avec la propriété msg comme paramètre de $t.

TIP

La clé de ressource de messages locaux pour la fonction de traduction peut être spécifiée pour un espace de noms de ressource spécifique en utilisant . (point), tout comme un objet JavaScript.

TIP

$t a plusieurs surcharges. À propos de ces surcharges, voir la Référence de l'API

Résultat :

<p>hello world</p>

Interpolation de liste

L'interpolation de liste peut être interpolée dans l'espace réservé en utilisant un tableau défini en JavaScript.

Par exemple, la ressource de messages locaux suivante :

const messages = {
  en: {
    message: {
      hello: '{0} world'
    }
  }
}

Elle définit la locale en avec { message: { hello: '{0} world' } }.

L'interpolation de liste vous permet de spécifier un tableau défini en JavaScript. Dans le message local ci-dessus, vous pouvez le localiser en donnant l'élément d'indice 0 du tableau défini par JavaScript comme paramètre à la fonction de traduction.

Voici un exemple d'utilisation de $t dans un template :

<p>{{ $t('message.hello', ['hello']) }}</p>

Le premier argument est message.hello comme clé de messages locaux, et le deuxième argument est un tableau ayant l'élément 'hello' comme paramètre de $t.

Résultat :

<p>hello world</p>

Interpolation littérale

L'interpolation littérale peut être interpolée dans l'espace réservé en utilisant une chaîne littérale.

Par exemple, la ressource de messages locaux suivante :

const messages = {
  en: {
    address: "{account}{'@'}{domain}"
  }
}

Elle définit la locale en avec { address: "{account}{'@'}{domain}" }.

L'interpolation littérale vous permet de spécifier une chaîne littérale entre guillemets simples ’. Le message spécifié avec l'interpolation littérale est localisé comme une chaîne par la fonction de traduction.

Voici un exemple d'utilisation de $t dans un template :

<p>email : {{ $t('address', { account: 'foo', domain: 'domain.com' }) }}</p>

Le premier argument est address comme clé de messages locaux, et le deuxième argument est un objet avec les propriétés account et domain comme paramètre de $t.

Résultat :

<p>email : [email protected]</p>

NOTE

L'interpolation littérale est utile pour les caractères spéciaux dans la syntaxe du format des messages, tels que { et }, qui ne peuvent pas être utilisés directement dans le message.

Messages liés

Si une clé de messages locaux aura toujours le même texte concret qu'une autre, vous pouvez simplement la lier.

Pour lier à une autre clé de messages locaux, il suffit de préfixer son contenu avec un signe @:key suivi du nom complet de la clé de messages locaux incluant l'espace de noms vers lequel vous souhaitez effectuer le lien.

Messages locaux ci-dessous :

const messages = {
  en: {
    message: {
      the_world: 'the world',
      dio: 'DIO:',
      linked: '@:message.dio @:message.the_world !!!!'
    }
  }
}

Il s'agit de la locale en qui a une structure hiérarchique dans l'objet.

Le message.the_world contient the world et message.dio. Le message.linked contient @:message.dio @:message.dio @:message.the_world !!!!, et il est lié aux clés de messages locaux avec message.dio et message.the_world.

Voici un exemple d'utilisation de $t dans un template :

<p>{{ $t('message.linked') }}</p>

Le premier argument est message.linked comme clé de messages locaux comme paramètre de $t.

Résultat :

<p>DIO: the world !!!!</p>

Modificateurs intégrés

Si la langue distingue les majuscules et minuscules des caractères, il se peut que vous ayez besoin de contrôler la casse des messages locaux liés. Les messages liés peuvent être formatés avec le modificateur @.modifier:key

Les modificateurs suivants sont actuellement disponibles intégralement.

• upper : Mettre tous les caractères en majuscules dans le message lié
• lower : Mettre tous les caractères en minuscules dans le message lié
• capitalize : Mettre la première lettre en majuscule dans le message lié

Messages locaux ci-dessous :

const messages = {
  en: {
    message: {
      homeAddress: 'Home address',
      missingHomeAddress: 'Please provide @.lower:message.homeAddress'
    }
  }
}

Il s'agit de la locale en qui a une structure hiérarchique dans l'objet.

Le message.homeAddress contient Home address. Le message.missingHomeAddress contient Please provide @.lower:message.homeAddress, et il est lié à la clé de messages locaux avec message.homeAddress.

Dans l'exemple ci-dessus, puisque le modificateur .lower est spécifié, la clé liée message.homeAddress est résolue, puis évaluée.

Voici un exemple d'utilisation de $t dans un template :

<label>{{ $t('message.homeAddress') }}</label>
<p class="error">{{ $t('message.missingHomeAddress') }}</p>

Résultat :

<label>Home address</label>
<p class="error">Please provide home address</p>

Modificateurs personnalisés

Si vous voulez utiliser des modificateurs non intégrés, vous pouvez utiliser vos propres modificateurs.

Pour utiliser des modificateurs personnalisés, vous devez les spécifier dans l'option modifiers de createI18n :

const i18n = createI18n({
  locale: 'en',
  messages: {
    // définir des messages locaux...
  },
  // définir les modificateurs personnalisés dans l'option `modifiers`
  modifiers: {
    snakeCase: (str) => str.split(' ').join('_')
  }
})

Messages locaux ci-dessous :

const messages = {
  en: {
    message: {
      snake: 'snake case',
      custom_modifier: "exemple de modificateurs personnalisés : @.snakeCase:{'message.snake'}"
    }
  }
}

Il s'agit de la locale en qui a une structure hiérarchique dans l'objet.

Le message.snake contient snake case. Le message.custom_modifier contient exemple de modificateurs personnalisés : @.snakeCase:{'message.snake'}, et il est lié à la clé de messages locaux, qui est interpolé avec une interpolation littérale.

NOTE

Vous pouvez utiliser les interpolations (Nomme, Liste et Littérale) pour la clé des messages liés montrés ci-dessous.

Cet exemple montre l'utilisation des modificateurs (@.lower, @.upper, @.capitalize) combinés avec les interpolations nommées, de liste et littérales.

const messages = {
  en: {
    message: {
      greeting: "Hello, @.lower:{'message.name'}! You have {count} new messages.",
      name:"{name}"
    },

    welcome: "Welcome, @.upper:{'name'}! Today is @.capitalize:{'day'}.",
    name: '{0}',
    day: '{1}',

    literalMessage: "This is an email: foo{'@'}@.lower:domain",
    domain: 'SHOUTING'
  }
}

Interpolation nommée avec modificateur

Dans message.greeting, nous utilisons une interpolation nommée pour {count} et nous lions à message.name, appliquant le modificateur .lower.

La clé message.name contient {name}, qui sera interpolé avec le paramètre name passé.

Le message.greeting est lié à la clé de message local message.name.

<p>{{ $t('message.greeting', { name: 'Alice', count: 5 }) }}</p>

Résultat :

<p>Hello, alice! You have 5 new messages.</p>

Interpolation de liste avec modificateur

Dans ce cas, les valeurs pour {0} et {1} sont passées sous forme de tableau. Les clés name et day sont résolues en utilisant l'interpolation de liste et transformées avec des modificateurs.

<p>{{ $t('welcome', ['bob', 'MONDAY']) }}</p>

Résultat :

<p>Welcome, BOB! Today is Monday.</p>

Interpolation littérale avec modificateur

Dans cet exemple, nous utilisons une chaîne littérale dans le message et appliquons le modificateur .lower.

<p>{{ $t('literalMessage') }}</p>

Ici, le modificateur est appliqué au contenu à l'intérieur de domain, et le @ est conservé comme sortie littérale.

Résultat :

<p>This is an email: foo@shouting</p>

Caractères spéciaux

Les caractères suivants utilisés dans la syntaxe de format des messages sont traités par le compilateur comme des caractères spéciaux :

• {
• }
• @
• $
• |

Si vous souhaitez utiliser ces caractères, vous devrez utiliser l'Interpolation littérale.

Format Rails i18n

Vue I18n prend en charge le format de message compatible avec Ruby on Rails i18n.

Vous pouvez interpoler la syntaxe de format des messages avec un préfixe % :

IMPORTANT

À partir de la version v10, le format Rails i18n sera déprécié. Nous recommandons d'utiliser l'interpolation nommée.

Par exemple, la ressource de messages locaux suivante :

const messages = {
  en: {
    message: {
      hello: '%{msg} world'
    }
  }
}

Elle définit la locale en avec { message: { hello: '%{msg} world' } }.

Comme avec l'interpolation nommée, vous pouvez spécifier les variables définies en JavaScript. Dans le message local ci-dessus, il est possible de le localiser en donnant une variable msg définie en JavaScript comme paramètre à la fonction de traduction.

Voici un exemple d'utilisation de $t dans un template :

<p>{{ $t('message.hello', { msg: 'hello' }) }}</p>

Résultat :

<p>hello world</p>

Message HTML

Vous pouvez le localiser avec des messages contenant du HTML.

DANGER

⚠️ La localisation dynamique de HTML arbitraire sur votre site peut être très dangereuse car elle peut facilement conduire à des vulnérabilités XSS. N'utilisez l'interpolation HTML que sur du contenu de confiance et jamais sur du contenu fourni par l'utilisateur.

Nous recommandons d'utiliser l'Interpolation de composant.

NOTICE

Si le message contient du HTML, Vue I18n affiche un avertissement dans la console en mode développement (process.env.NODE_ENV !== 'production'), Vue I18n affiche un avertissement dans la console.

Vous pouvez contrôler la sortie de l'avertissement avec les options warnHtmlInMessage ou warnHtmlMessage dans createI18n ou useI18n.

Par exemple, la ressource de messages locaux suivante :

const messages = {
  en: {
    message: {
      hello: 'hello <br> world'
    }
  }
}

Elle définit la locale en avec { message: { hello: 'hello <br> world' } }.

Voici un exemple d'utilisation de v-html et $t dans un template :

<p v-html="$t('message.hello')"></p>

Résultat :

<p>hello
<!--<br> existe mais est rendu comme html et non comme une chaîne-->
world</p>