Поддержка TypeScript

Поддерживаемые версии

🆕 9.2+

VueI18n использует ресурсы, такие как сообщения локали, форматы даты и времени и числа. В частности, сообщения локали могут быть экспортированы как i18n ресурсы, например, в виде файлов json, чтобы сотрудничать с переводчиками, используя службу локализации, и эти ресурсы могут быть импортированы для совместной работы.

Чтобы обеспечить плавный рабочий процесс локализации в сочетании со службой локализации, вы можете избежать отсутствующих локализаций или отсутствующих определений ресурсов для экспортированных i18n ресурсов. А в разработке вы можете не испортить опыт разработчика, предотвращая ошибки с ключевыми строками при использовании функции перевода, такой как $t.

Типобезопасные ресурсы со схемой

Вы можете поддерживать типобезопасные ресурсы со схемой ресурсов, используя TypeScript.

Типобезопасные ресурсы в `createI18n`

Следующий пример кода демонстрирует определение типобезопасных ресурсов для messages, определенных с параметром createI18n.

Ресурс сообщений локали:

json

{
  "world": "the world!"
}

Точка входа приложения:

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

// Определите тип 'en-US' как главную схему ресурса
type MessageSchema = typeof enUS

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

Приведенный выше код определяет тип из ресурса сообщения en-US, указанного в параметре messages функции createI18n. Этот определенный тип является главной схемой для ресурсов сообщений, обрабатываемых с помощью VueI18n. Это означает, что вы можете определить его как единый источник истины ресурсов в вашем приложении. Вы можете определить типобезопасный ресурс для других локалей, указав тип, определенный как схема из ресурса сообщения, как первый аргумент параметра типа createI18n.

Вторым аргументом параметра типа createI18n является локаль для обработки. С этим, проверка типов выполняется для каждой указанной локали во втором аргументе, основываясь на типе ресурса, указанном в первом аргументе. В приведенном выше примере кода en-US и ja-JP указаны как основная локаль, которая также указана в параметре locale. Если вы скомпилируете Typescript в этом состоянии, вы получите следующую ошибку для проверки того, что ресурс ja-JP не определен в параметре messages.

$ npx tsc
npx tsc
src/main.ts:11:3 - error TS2741: Property '"ja-JP"' is missing in type '{ 'en-US': { world: string; }; }' but required in type '{ "en-US": { world: string; }; "ja-JP": { world: string; }; }'.

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

  node_modules/vue-i18n/dist/vue-i18n.d.ts:712:5
    712     messages?: {
            ~~~~~~~~
    The expected type comes from property 'messages' which is declared here on type 'I18nOptions<{ message: { world: string; }; datetime: DateTimeFormat; number: NumberFormat; }, { messages: "en-US"; datetimeFormats: "en-US"; numberFormats: "en-US"; } | { ...; }, ComposerOptions<...> | VueI18nOptions<...>>'


Found 1 error.

Если вы используете Visual Studio Code в качестве редактора, вы можете заметить, что в редакторе отсутствует определение ресурса с ошибкой, прежде чем запустите компиляцию Typescript.

VSCode-Type-Error1 VSCode-Type-Error2

Типобезопасные ресурсы в `useI18n`

Типобезопасные ресурсы могут быть определены не только с помощью createI18n, но и на уровне компонента с помощью useI18n, используемого с Composition API.

Помимо локальных сообщений, определения типов ресурсов также могут включать форматы даты и времени и чисел.

Следующий пример кода демонстрирует определение типобезопасных ресурсов для сообщений локали и форматов чисел на уровне компонента с помощью useI18n.

Сообщения локали для импорта в компоненты Vue:

json

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

Компоненты Vue с типобезопасными ресурсами:

vue

<script setup lang="ts">
import { useI18n } from 'vue-i18n'
import enUS from './en-US.json' // импорт сообщений локали для компонента Vue

// определить схему сообщений для компонента Vue
type MessageSchema = typeof enUS

// определить схему формата числа для компонента Vue
type NumberSchema = {
  currency: {
    style: 'currency'
    currencyDisplay: 'symbol'
    currency: string
  }
}

/*
 * Вы можете указать свою определенную схему с помощью литерала объекта в первом параметре типа
 * О параметрах типа см. 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>currency: {{ n(1000, 'currency') }}</p>
</template>

В приведенном выше коде, указав определенную схему как первый параметр типа useI18n, вы можете использовать TypeScript для проверки отсутствующих ресурсов для сообщений локали и форматов чисел. Также, указав локаль для определения во втором параметре типа, TypeScript может проверять отсутствие локалей.

Ограничения

Типобезопасность не поддерживается для пользовательских блоков i18n в SFC. Мы планируем поддерживать это в будущем.
В настоящее время поддерживается только формат JSON.

Описанный выше код доступен как пример. Давайте проверим его!

API с поддержкой типобезопасности

Другие API поддерживают параметр типа, который позволяет указать схему ресурса для манипуляции типобезопасными ресурсами, например:

getLocaleMessage
setLocaleMessage
mergeLocaleMessage
getDateTimeFormat
setDateTimeFormat
mergeDateTimeFormat
getNumberFormat
setNumberFormat
mergeNumberFormat

За дополнительной информацией обращайтесь к страницам документации следующих API:

Поддержка завершения ключей ресурсов

УВЕДОМЛЕНИЕ

Завершение ключей ресурсов может использоваться, если вы используете Visual Studio Code

Вместе с поддержкой типобезопасных определений ресурсов VueI18n теперь предоставляет APIs, такие как t и d для интерполяции ключей ресурсов в Composition API.

Следующее показывает, как интерполировать ключи ресурсов в Visual Studio Code для локального компонента Vue, описанного выше.

VSCode-Resource-Completion

Поддержка интерполяции ключей ресурсов может предотвратить пропущенные переводы.

В ваших проектах вы можете иметь компоненты Vue, которые не используют локальную область видимости, а используют глобальную область для всего.

Для этой задачи вы также можете поддерживать интерполяцию ключей ресурсов, явно указав схему, определенную для глобальной области видимости, в параметре типа useI18n.

Определить схему для глобальной области видимости:

/**
 * определить схему ресурса
 */

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

// определить схему сообщения как главную схему сообщений
export type MessageSchema = typeof enUS

// определить схему формата числа
export type NumberSchema = {
  currency: {
    style: 'currency'
    currencyDisplay: 'symbol'
    currency: string
  }
}

Затем просто импортируйте определенную схему и используйте ее как параметр типа useI18n, как в следующем компоненте Vue:

vue

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

// импортируем схему ресурса для глобальной области видимости
import type { MessageSchema, NumberSchema } from '../locales/schema'

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

<template>
  <p>сообщение: {{ t('hello') }}</p>
  <p>валюта: {{ n(1000, 'currency') }}</p>
</template>

В результате вы можете использовать интерполяцию ключей ресурсов в APIs, предоставленных VueI18n, таких как t и n.

УВЕДОМЛЕНИЕ

Режим устаревшего API, и интерполяция ключей ресурсов в APIs, таких как $t и $d, которые внедряются в компонент посредством globalInjection: true в Composition API, требуют явного указания параметров типа.

За дополнительной информацией обращайтесь к документации API. https://vue-i18n.intlify.dev/api/injection.html

Глобальное определение типа схемы ресурса

В VueI18n вы можете определить типы ресурсов на уровне глобальной области видимости, используя функцию TypeScript по расширению интерфейсов.

Если ваш проект использует все ресурсы в глобальной области видимости, это очень удобно для простого управления типобезопасными ресурсами.

VueI18n предоставляет следующие интерфейсы:

DefineLocaleMessage: Интерфейс для глобального определения схемы сообщений локали
DefineDateTimeFormat: Интерфейс для глобального определения схемы форматов даты и времени
DefineNumberFormat: Интерфейс для глобального определения схемы форматов чисел

Используя эти интерфейсы и declare module, вы можете определить глобальную схему для VueI18n.

Следующий пример представляет собой глобальную схему, определенную в d.ts:

/**
 * вам нужно импортировать некоторые интерфейсы
 */


declare module 'vue-i18n' {
  // определить схему сообщений локали
  export interface DefineLocaleMessage {
    hello: string
    menu: {
      login: string
    }
    errors: string[]
  }

  // определить схему формата даты и времени
  export interface DefineDateTimeFormat {
    short: {
      hour: 'numeric'
      minute: 'numeric'
      second: 'numeric'
      timeZoneName: 'short'
      timezone: string
    }
  }

  // определить схему формата числа
  export interface DefineNumberFormat {
    currency: {
      style: 'currency'
      currencyDisplay: 'symbol'
      currency: string
    }
  }
}

Используя declare module и интерфейсы, предоставляемые VueI18n, вы можете определить схему для глобальных ресурсов.

Ранее, когда использовались createI18n и useI18n с определениями типов для глобальной области видимости ресурсов, было необходимо указывать каждый из них как параметр типа. Таким образом, вам больше не нужно этого делать.

Следующий пример с createI18n:

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

/**
 * импортируем ресурс сообщений локали из json для глобальной области видимости
 */
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'
      }
    }
  }
}

/**
 * настройка vue-i18n с i18n ресурсами с глобальным определением типа.
 * если вы определяете схему i18n ресурса в вашем `*.d.ts`, они будут проверяться с помощью typeScript.
 */
const i18n = createI18n<false, typeof options>(options)

Первым параметром типа createI18n выше не указан тип, который является схемой ресурса. Приведенное выше просто указывает подсказку типа для свойства global экземпляра i18n, созданного createI18n. (Если false, тип - это экземпляр Composer для Composition API, если true, тип - это экземпляр VueI18n для устаревшего API)

Второй параметр типа createI18n указывает подсказку типа для опций.

В случае использования useI18n с компонентами Vue, это выглядит так:

vue

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

// использование глобальной области видимости
const { t, d, n } = useI18n({
  inheritLocale: true
})
</script>

<template>
  <p>`t` resource key completion: {{ t('menu.login') }}</p>
  <p>`d` resource key completion: {{ d(new Date(), 'short') }}</p>
  <p>`n` resource key completion: {{ n(1000, 'currency') }}</p>
</template>

Как вы можете видеть из приведенного выше кода, вам не нужно указывать ничего для параметра типа useI18n. Вы можете интерполировать ключи ресурсов API, такие как t, d и n, без их указания.

general

Variables

Functions

Interfaces

Type Aliases

vue

Interfaces

Поддержка TypeScript

Типобезопасные ресурсы со схемой

Типобезопасные ресурсы в `createI18n`

Типобезопасные ресурсы в `useI18n`

API с поддержкой типобезопасности

Поддержка завершения ключей ресурсов

Глобальное определение типа схемы ресурса

Поддержка TypeScript ​

Типобезопасные ресурсы со схемой ​

Типобезопасные ресурсы в createI18n ​

Типобезопасные ресурсы в useI18n ​

API с поддержкой типобезопасности ​

Поддержка завершения ключей ресурсов ​

Глобальное определение типа схемы ресурса ​

Поддержка TypeScript

Типобезопасные ресурсы со схемой

Типобезопасные ресурсы в `createI18n`

Типобезопасные ресурсы в `useI18n`

API с поддержкой типобезопасности

Поддержка завершения ключей ресурсов

Глобальное определение типа схемы ресурса