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 注入类型系统。
• 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 模板中使用

 复制代码

TypeScript 脚本中使用

在 中调用 useI18n 即可获得类型提示：

 复制代码

进阶：封装 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 的拼写错误，无需等到运行时才暴露问题。整个流程兼顾了类型安全与开发体验的流畅性。