Vue-i18n 与 TypeScript 集成实现自动补全与类型提示完整指南

Vue-i18n 作为 Vue 生态中最常用的国际化解决方案，其默认的 TypeScript 类型提示能力却十分有限 —— 在默认情况下，$t('key') 的参数类型仅为 string，即便传入错误的 key 也不会触发任何编译报错。下面分享一套基于 JSON 语言文件与模块增强的配置方案，让 IDE 能够自动提示所有翻译 key，并在传入不存在的 key 时直接抛出类型错误。

环境准备

本文以 Vue 3 + Vite + TypeScript 项目为基础，vue-i18n 的版本为 v11.4.6。其他版本的核心原理完全相同，按照以下步骤操作即可顺利实现。

项目结构

 复制代码root/
│── src/
│   ├── locales/            # 语言文件目录
│   │   ├── index.ts        # 语言文件索引（导出所有 locale）
│   │   ├── en-US.json      # 英文语言文件
│   │   └── zh-CN.json      # 中文语言文件
│   ├── App.vue
│   ├── main.ts
│   ├── global.d.ts         # 全局类型声明
│   ├── composables/
│   │   └── useTranslation.ts  # 封装 t 函数
├── index.html
├── vite.config.ts
└── package.json

第一步：准备语言文件

语言文件统一采用 JSON 格式，key 的层级结构将直接决定后续类型提示的路径。建议按照功能模块进行组织，便于后续复用与维护。

 复制代码// src/locales/en-US.json
{
  "message": {
    "hello": "Hello World",
    "description": "This is a description"
  },
  "na v": {
    "home": "Home",
    "about": "About"
  }
}

 复制代码// src/locales/zh-CN.json
{
  "message": {
    "hello": "你好世界",
    "description": "这是一段描述"
  },
  "na v": {
    "home": "首页",
    "about": "关于"
  }
}

第二步：导出语言文件索引

在 src/locales/index.ts 中，将所有语言文件按照 locale 名称统一导出，注意添加 as const 以确保类型推断更加精确。

 复制代码import enUS from './en-US.json'
import zhCN from './zh-CN.json'export default {
  'en-US': enUS,
  'zh-CN': zhCN
} as const

第三步：全局类型声明

创建 src/global.d.ts，借助模块增强（Module Augmentation）让 vue-i18n 能够识别你的语言文件结构。核心步骤是扩展 DefineLocaleMessage 接口。

 复制代码import type { DefineLocaleMessage } from 'vue-i18n'
import locales from './locales'declare global {
  // 将语言文件结构暴露为全局类型，方便在其他地方引用
  type MessageSchema = (typeof locales)['en-US']
}// vue-i18n@9+ 模块增强
declare module 'vue-i18n' {
  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
  interface DefineLocaleMessage extends MessageSchema {}
  interface GeneratedTypeConfig {
    locale: keyof typeof locales
  }
}

关键点解释

• DefineLocaleMessage：这是 vue-i18n 用于约束翻译消息结构的核心接口，扩展它等同于将所有语言文件的 key 注入到 TypeScript 类型系统中。
• MessageSchema：从 locales 的 'en-US' 值推导出的类型，完整映射了所有翻译 key 的层级结构。
• GeneratedTypeConfig：约束 locale 的类型，确保只能传入 locales 中已定义的语言标识（本文中为 en-US 和 zh-CN）。

第四步：初始化 VueI18n 实例

在 main.ts 中完成 i18n 实例的初始化，并将语言文件传入。注意启用 Composition API 模式（设置 legacy: false）。

 复制代码import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'
import App from './App.vue'
import locales from './locales'const i18n = createI18n({
  legacy: false, // 使用 Composition API 模式
  locale: 'zh-CN',
  fallbackLocale: 'en-US',
  messages: locales
})const app = createApp(App)
app.use(i18n)
app.mount('#app')

第五步：在组件中使用

SFC 模板中使用

 复制代码

TS 脚本中使用

在

进阶：封装 composable 实现严格类型检查

原生 t 函数的参数类型默认为 string，即使传入不存在的 key 也不会在编译阶段报错（参考 vue-i18n issue #1116）。如果需要更严格的类型约束，可以封装一个自定义 useTranslation composable，进一步限制 key 的合法取值。

创建 src/composables/useTranslation.ts：

 复制代码import type { NamedValue } from 'vue-i18n'
import { useI18n } from 'vue-i18n'// 递归提取对象的所有叶子路径，如 "message.hello"
type PathToLea vesCache extends string = ''> = T extends PropertyKey
  ? Cache
  : {
      [P in keyof T]: P extends string
        ? Cache extends ''
          ? PathToLea ves`${P}`>
          : PathToLea ves`${Cache}.${P}`>
        : never
    }[keyof T]type TranslationPaths = PathToLea ves<MessageSchema>export const useTranslation = () => {
  const { t } = useI18n<{ messages: MessageSchema }>()  return {
    t: <const Path extends TranslationPaths>(path: Path, named?: NamedValue) => (named ? t(path, named) : t(path))
  }
}

使用封装后的 t

 复制代码

完成上述配置后，你的 Vue-i18n 将拥有完整的 TypeScript 类型提示能力，在编译阶段就能及时发现翻译 key 的拼写错误，无需等到运行时才暴露问题。整套方案既保障了类型安全，又确保了开发体验的流畅与高效。