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 模板中使用
复制代码
{{ $t('message.hello') }}
{{ $t('message.description') }}
{{ $t('na v.home') }}
{{ $t('na v.about') }}
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 的拼写错误，无需等到运行时才暴露问题。整套方案既保障了类型安全，又确保了开发体验的流畅与高效。
