Support TypeScript

Versions prises en charge

🆕 9.2+

VueI18n utilise les ressources, qui comprennent les messages locaux, les formats de date et les formats numériques. En particulier, les messages locaux peuvent être externalisés en tant que ressources i18n, telles que des fichiers json, afin de collaborer avec les traducteurs en utilisant le service de localisation, et ces ressources peuvent être importées pour la collaboration.

Afin d'obtenir un flux de travail de localisation fluide en conjonction avec le service de localisation, vous pouvez vouloir éviter les localisations manquantes ou les définitions de ressources manquantes pour les ressources i18n externalisées. Et en développement, vous ne souhaitez pas nuire à l'expérience développeur en empêchant les erreurs de chaînes de clés lors de l'utilisation de fonctions de traduction comme $t.

Ressources sécurisées par le type avec schéma

Vous pouvez prendre en charge les ressources sécurisées par le type avec schéma en utilisant TypeScript.

Ressources sécurisées par le type dans `createI18n`

Le code suivant est un exemple de code pour définir des ressources sécurisées par le type pour messages définies avec l'option createI18n.

Ressource de messages locaux :

json

{
  "world": "le monde !"
}

Point d'entrée de l'application :

import { createI18n } from 'vue-i18n'
import enUS from './locales/en-US.json'

// Définir 'en-US' comme schéma principal pour la ressource
type MessageSchema = typeof enUS

const i18n = createI18n<[MessageSchema], 'en-US' | 'ja-JP'>({
  locale: 'en-US',
  messages: {
    'en-US': enUS
  }
})

Le code ci-dessus définit un type à partir de la ressource de message en-US spécifiée dans l'option messages de createI18n. Ce type défini est le schéma principal pour les ressources de message gérées avec VueI18n. Cela signifie que vous pouvez le définir comme une seule source de vérité pour les ressources de votre application. Vous pouvez définir des ressources sécurisées par le type dans d'autres langues en spécifiant le type défini comme schéma à partir d'une ressource de message comme premier argument du paramètre de type de createI18n.

Le deuxième argument du paramètre de type de createI18n est la locale à gérer. Avec cela, une vérification de type est effectuée pour chaque locale spécifiée dans le deuxième argument, basée sur le type de ressource spécifié dans le premier argument. Dans l'exemple de code ci-dessus, en-US et ja-JP sont spécifiés comme locale principale, qui est également spécifiée dans l'option locale. Si vous compilez typescript dans cet état, vous obtiendrez l'erreur suivante pour vérifier qu'aucune ressource ja-JP n'est définie dans l'option messages.

$ npx tsc
npx tsc
src/main.ts:11:3 - error TS2741 : La propriété '"ja-JP"' est manquante dans le type '{ 'en-US': { world: string; }; }' mais requise dans le type '{ "en-US": { world: string; }; "ja-JP": { world: string; }; }'.

11   messages: {
     ~~~~~~~~

  node_modules/vue-i18n/dist/vue-i18n.d.ts:712:5
    712     messages?: {
            ~~~~~~~~
    Le type attendu provient de la propriété 'messages' déclarée ici sur le type 'I18nOptions<{ message: { world: string; }; datetime: DateTimeFormat; number: NumberFormat; }, { messages: "en-US"; datetimeFormats: "en-US"; numberFormats: "en-US"; } | { ...; }, ComposerOptions<...> | VueI18nOptions<...>>'

Found 1 error.

Si vous utilisez Visual Studio Code comme éditeur, vous pouvez remarquer qu'il y a une omission de définition de ressource dans l'éditeur avec l'erreur suivante avant d'exécuter la compilation typescript.

VSCode-Type-Error1 VSCode-Type-Error2

Ressources sécurisées par le type dans `useI18n`

Les ressources sécurisées par le type peuvent être définies non seulement avec createI18n, mais aussi au niveau composant avec useI18n utilisé avec l'API Composition.

En plus des messages locaux, les définitions de type de ressources peuvent également inclure les formats de date et les formats numériques.

L'exemple suivant montre un code qui définit des ressources sécurisées par le type pour les messages locaux et les formats numériques au niveau composant dans useI18n.

Messages locaux à importer dans les composants Vue :

json

{
  "messages": {
    "hello": "Bonjour, {name} !"
  }
}

Composants Vue avec ressources sécurisées par le type :

vue

<script setup lang="ts">
import { useI18n } from 'vue-i18n'
import enUS from './en-US.json' // importer les messages locaux pour le composant Vue

// définir le schéma de message pour le composant Vue
type MessageSchema = typeof enUS

// définir le schéma de format numérique pour le composant Vue
type NumberSchema = {
  currency: {
    style: 'currency'
    currencyDisplay: 'symbol'
    currency: string
  }
}

/*
 * Vous pouvez spécifier votre schéma de définition avec un littéral objet au premier paramètre de type
 * À propos du paramètre de type, voir http://vue-i18n.intlify.dev/api/composition.html#usei18n
 */
const { t, n } = useI18n<{
  message: MessageSchema,
  number: NumberSchema
}, 'en-US'>({
  inheritLocale: true,
  messages: {
    'en-US': enUS
  },
  numberFormats: {
    'en-US': {
      currency: {
        style: 'currency',
        currencyDisplay: 'symbol',
        currency: 'USD'
      }
    }
  }
})
</script>

<template>
  <p>message : {{ t('messages.hello', { name: 'kazupon' }) }}</p>
  <p>monnaie : {{ n(1000, 'currency') }}</p>
</template>

Dans le code ci-dessus, en spécifiant le schéma défini comme premier paramètre de type de useI18n, vous pouvez utiliser TypeScript pour vérifier les ressources non définies pour les messages locaux et les formats numériques. De plus, en spécifiant la locale à définir dans le deuxième paramètre de type, TypeScript peut vérifier les locales non définies.

Limitation

La sécurité de type n'est pas prise en charge pour les blocs i18n personnalisés dans SFC. Nous prévoyons de la prendre en charge dans le futur.
Prise en charge actuelle uniquement pour le format JSON.

Le code décrit ci-dessus est disponible sous forme d'exemple. Vérifions-le !

API prenant en charge la sécurité de type

D'autres API prennent en charge un paramètre de type qui vous permet de spécifier le schéma d'une ressource pour la manipulation sécurisée par le type de ressources, telles que :

getLocaleMessage
setLocaleMessage
mergeLocaleMessage
getDateTimeFormat
setDateTimeFormat
mergeDateTimeFormat
getNumberFormat
setNumberFormat
mergeNumberFormat

Pour plus de détails, consultez ces pages de documentation d'API suivantes.

Support de la complétion des clés de ressources

AVERTISSEMENT

La complétion des clés de ressources peut être utilisée si vous utilisez Visual Studio Code

Avec le support des définitions de ressources sécurisées par le type, VueI18n fournit maintenant des API telles que t et d pour interpoler les clés de ressources dans l'API Composition.

Le suivant indique comment interpoler les clés de ressources dans Visual Studio Code pour le composant Vue à portée locale décrit ci-dessus.

VSCode-Resource-Completion

Le support de l'interpolation des clés de ressources peut empêcher les traductions manquantes.

Dans les cas d'utilisation de votre projet, vous pouvez avoir des composants Vue qui n'utilisent pas de portée locale, mais utilisent la portée globale pour tout.

Pour ce cas d'utilisation, vous pouvez également prendre en charge l'interpolation des clés de ressources en spécifiant explicitement le schéma défini pour la portée globale dans le paramètre de type de useI18n.

définir le schéma pour la portée globale :

/**
 * définir le schéma de ressource
 */

import enUS from './en-US.json'

// définir le schéma de message comme schéma de message principal
export type MessageSchema = typeof enUS

// définir le schéma de format numérique
export type NumberSchema = {
  currency: {
    style: 'currency'
    currencyDisplay: 'symbol'
    currency: string
  }
}

Ensuite, il suffit d'importer le schéma défini et de l'utiliser comme paramètre de type de useI18n, comme dans le composant Vue suivant :

vue

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

// importer le schéma de ressource pour la portée globale
import type { MessageSchema, NumberSchema } from '../locales/schema'

const { t, n } = useI18n<{ message: MessageSchema, number: NumberSchema }>({
  useScope: 'global'
})
</script>

<template>
  <p>message : {{ t('hello') }}</p>
  <p>monnaie : {{ n(1000, 'currency') }}</p>
</template>

En conséquence, vous pouvez utiliser l'interpolation des clés de ressources dans les API fournies par VueI18n, telles que t et n.

AVERTISSEMENT

Mode hérité, et l'interpolation des clés de ressources des API telles que $t et $d, injectées dans le composant par globalInjection: true de l'API Composition, nécessitent de spécifier explicitement les paramètres de type.

Pour plus de détails, consultez la documentation de l'API. https://vue-i18n.intlify.dev/api/injection.html

Définition de type de schéma de ressource globale

Dans VueI18n, vous pouvez définir les types de ressources au niveau de la portée globale en utilisant la fonctionnalité TypeScript pour étendre les interfaces.

Si votre projet utilise toutes les ressources en portée globale, il est très pratique de manipuler facilement les ressources sécurisées par le type.

VueI18n fournit les interfaces suivantes :

DefineLocaleMessage : Interface pour définir globalement le schéma des messages locaux
DefineDateTimeFormat : Interface pour définir globalement le schéma des formats de date
DefineNumberFormat : Interface pour définir globalement le schéma des formats numériques

En utilisant ces interfaces et declare module, vous pouvez définir un schéma global pour VueI18n.

Voici un exemple de schéma global défini dans d.ts :

/**
 * vous devez importer certaines interfaces
 */



declare module 'vue-i18n' {
  // définir le schéma des messages locaux
  export interface DefineLocaleMessage {
    hello: string
    menu: {
      login: string
    }
    errors: string[]
  }

  // définir le schéma du format de date
  export interface DefineDateTimeFormat {
    short: {
      hour: 'numeric'
      minute: 'numeric'
      second: 'numeric'
      timeZoneName: 'short'
      timezone: string
    }
  }

  // définir le schéma du format numérique
  export interface DefineNumberFormat {
    currency: {
      style: 'currency'
      currencyDisplay: 'symbol'
      currency: string
    }
  }
}

En utilisant declare module et les interfaces fournies par VueI18n, vous pouvez définir le schéma pour les ressources globales.

Précédemment, lors de l'utilisation de createI18n et useI18n avec des définitions de type pour les ressources de portée globale, il était nécessaire de spécifier chacune comme paramètre de type. De cette façon, vous n'avez plus besoin de le faire.

L'exemple suivant avec createI18n :

import { createI18n, type I18nOptions } from 'vue-i18n'

/**
 * importer la ressource de messages locaux depuis json pour la portée globale
 */
import enUS from './locales/en-US.json'
import jaJP from './locales/ja-JP.json'

const options: I18nOptions = {
  legacy: false,
  locale: 'ja-JP',
  fallbackLocale: 'en-US',
  messages: {
    'en-US': enUS,
    'ja-JP': jaJP
  },
  datetimeFormats: {
    'ja-JP': {
      short: {
        hour: 'numeric',
        minute: 'numeric',
        second: 'numeric',
        timeZoneName: 'short',
        timezone: 'Asia/Tokyo'
      }
    }
  },
  numberFormats: {
    'ja-JP': {
      currency: {
        style: 'currency',
        currencyDisplay: 'symbol',
        currency: 'JPY'
      }
    }
  }
}

/**
 * configurer vue-i18n avec des ressources i18n avec définition de type globale.
 * si vous définissez le schéma de ressource i18n dans votre `*.d.ts`, ceux-ci sont vérifiés avec typeScript.
 */
const i18n = createI18n<false, typeof options>(options)

Le premier paramètre de type de createI18n ci-dessus ne spécifie pas le type qui est le schéma de la ressource. Le ci-dessus spécifie simplement un indice de type pour la propriété global de l'instance i18n créée par createI18n. (Si false, le type est une instance Composer pour l'API Composition, si true, le type est une instance VueI18n pour l'API héritée)

Le deuxième paramètre de type de createI18n spécifie un indice de type pour les options.

Dans le cas de l'utilisation de useI18n par des composants Vue, cela ressemble à ceci :

vue

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

// utiliser la portée globale
const { t, d, n } = useI18n({
  inheritLocale: true
})
</script>

<template>
  <p>complétion de clé de ressource `t` : {{ t('menu.login') }}</p>
  <p>complétion de clé de ressource `d` : {{ d(new Date(), 'short') }}</p>
  <p>complétion de clé de ressource `n` : {{ n(1000, 'currency') }}</p>
</template>

Comme vous pouvez le voir dans le code ci-dessus, vous n'avez besoin de rien spécifier pour le paramètre de type de useI18n. Vous pouvez interpoler les clés de ressources d'API telles que t, d et n sans les spécifier.

general

Variables

Functions

Interfaces

Type Aliases

vue

Interfaces

Support TypeScript

Ressources sécurisées par le type avec schéma

Ressources sécurisées par le type dans `createI18n`

Ressources sécurisées par le type dans `useI18n`

API prenant en charge la sécurité de type

Support de la complétion des clés de ressources

Définition de type de schéma de ressource globale

Support TypeScript ​

Ressources sécurisées par le type avec schéma ​

Ressources sécurisées par le type dans createI18n ​

Ressources sécurisées par le type dans useI18n ​

API prenant en charge la sécurité de type ​

Support de la complétion des clés de ressources ​

Définition de type de schéma de ressource globale ​

Support TypeScript

Ressources sécurisées par le type avec schéma

Ressources sécurisées par le type dans `createI18n`

Ressources sécurisées par le type dans `useI18n`

API prenant en charge la sécurité de type

Support de la complétion des clés de ressources

Définition de type de schéma de ressource globale