本文详解 Vue3 国际化开发全流程：从安装 vue-i18n@next 到配置多语言文件（JSON/YAML），结合 i18n-Ally 插件实现高效翻译管理。重点涵盖：
- 工程配置：创建 i18n 实例、模块化语言文件结构（支持命名空间）、注册至 Vue 应用。
- 插件优化：通过 settings.json 配置路径、键名风格、翻译引擎（Google/DeepL），实现代码内联翻译显示。
- 避坑指南：关闭只读模式、选择可编辑格式（避免 JS/TS）、路径与依赖校验。
一、安装vue-i18n
vue3项目需要安装 vue-i18n@next 版本 使用 vue3-i18n将无法使用i18n-Ally插件
npm install vue-i18n@next
pnpm install vue-i18n@next
yarn add vue-i18n@next
二、vue3工程配置
1.创建i18n入口文件
//语言
import { lang } from '@/settings/designSetting'
import { createI18n } from 'vue-i18n' //引入vue-i18n组件
import zh from './zh/index'
import en from './en/index'
const i18n = createI18n({
legacy: false,
globalInjection:true,
locale: "ZH",
fallbackLocale: "ZH",
messages: {
ZH: zh,
EN: en
}
})
export default i18n
2.创建翻译文件.
推荐使用 YAML 和 JSON 格式，其他格式默认禁用。
i18n/en/login.json
{
"desc": "Login",
"form_auto": "Sign in automatically",
"form_button": "Login",
"login_success": "Login success",
"login_message": "Please complete the letter"
}
i18n/zh/login.json
{
"desc": "登录",
"form_auto": "自动登录",
"form_button": "登录",
"login_success": "登录成功",
"login_message": "请填写完整信息"
}
i18n/zh/index.ts
import login from './login.json'
const global = {
// 系统设置
sys_set: '系统设置',
contact: '关于软件',
logout: '退出登录',
}
export default {
global,
login
}
整体结构
3.main.js导入i18n依赖
import i18n from '@/i18n/index'
const app = createApp(App)
// 语言注册
app.use(i18n)
// 挂载到页面
app.mount('#app', true)
三、i18n-ally插件安装与配置
i18n是常见的语言国际化工具，但是在代码里查看的时候不能直接看到中文，往往需要去配置文件查看翻译内容。
这时候就需要vscode插件 i18n-Ally 来提高效率了
1. vscode插件市场搜索 i18n-Ally 并安装
2. settings.json配置
推荐将配置文件设置到.vscode/settings.json,当然也可以设置到vscode全局
这里我的i18n翻译文件路径是 src/i18n ，可以根据自己的文件路径修改。
我的文件路径是嵌套结构所以需要启用命名空间
"i18n-ally.keystyle": "nested", //nested 嵌套格式 flat 扁平格式
"i18n-ally.enabledFrameworks": ["vue", "vscode"], //启用框架
"i18n-ally.localesPaths": ["src/i18n"], //语言的文件路径
"i18n-ally.enabledParsers": ["ts","json"], //自动解析路径
"i18n-ally.namespace": true, //启用命名空间
"i18n-ally.sortKeys": true, //启用排序
"i18n-ally.pathMatcher": "{locale}/{namespaces}.{ext}", //文件命名规则
"i18n-ally.sourceLanguage": "zh", // 源语言
"i18n-ally.displayLanguage": "zh-CN", // 显示语言
没用嵌套文件可以使用以下配置文件 文件路径示例：src/lang
"i18n-ally.keystyle": "nested", //nested 嵌套格式 flat 扁平格式
"i18n-ally.localesPaths": ["src/lang"], //语言的文件路径
"i18n-ally.enabledParsers": ["ts","json"], //自动解析路径
"i18n-ally.sourceLanguage": "zh", // 源语言
"i18n-ally.displayLanguage": "zh-CN", // 显示语言
配置完就可以在项目工程文件里看到默认显示的翻译内容
四、常见问题
1. 插件处于只读模式
i18n-Ally 默认启用了 readonly 配置，或相关语言文件被设置为只读状态，导致无法自动填充缺失的翻译字段 。
在 .vscode/settings.json 中添加或修改以下配置：
{
"i18n-ally.readonly": false // 关闭只读模式
}
确保该文件位于项目根目录的 .vscode 文件夹下 。
2. 文件格式不支持写入
i8n-Ally插件支持格式如下，若语言文件格式为 JavaScript/TypeScript 等只读格式，插件无法直接修改文件内容
| Format | Read | Write | Annotations | Note |
|---|---|---|---|---|
| JSON | ✅ | ✅ | ✅ | |
| YAML | ✅ | ✅ | ✅ | Comments will NOT be preserved* |
| JSON5 | ✅ | ✅ | ❌ | Comments will NOT be preserved* |
| INI | ✅ | ✅ | ❌ | Comments will NOT be preserved* |
| properties | ✅ | ✅ | ❌ | Comments will NOT be preserved* |
| POT | ✅ | ✅ | ❌ | |
| JavaScript | ✅ | ❌ | ❌ | Read-only |
| TypeScript | ✅ | ❌ | ❌ | Read-only |
| PHP | ✅ | ❌ | ❌ | Read-only |
3. 配置文件路径错误
.vscode/settings.json 未放置在项目根目录（与 package.json 同级），导致配置未生效。
settings.json只能管理项目一级，不能多层项目嵌套，同时应用多个项目。
4. 依赖未正确安装
项目中未安装 vue-i18n 插件功能受限， 使用vue3-i18n 会导致插件无效。
五、参考资料
基础配置模板（settings.json）
// .vscode/settings.json
{
// 基础路径与文件格式
"i18n-ally.localesPaths": ["src/locales"], // 语言文件目录，支持数组和通配符
"i18n-ally.enabledParsers": ["json", "yaml"], // 可编辑文件格式（JSON/YAML支持读写注释）
"i18n-ally.pathMatcher": "{locale}/{namespaces}.{ext}", // 文件路径匹配规则（支持命名空间）
// 翻译核心设置
"i18n-ally.sourceLanguage": "zh-CN", // 源语言（翻译基准）
"i18n-ally.translate.engines": ["google-cn", "deepl"], // 翻译引擎（顺序优先）
"i18n-ally.keepFulfilled": true, // 自动填充空字符串避免字段缺失
// 键名结构与显示优化
"i18n-ally.keystyle": "nested", // 键名风格（nested嵌套 / flat平铺）
"i18n-ally.displayLanguage": "zh-CN", // 代码内联提示的显示语言
"i18n-ally.sortKeys": true, // 保存时按键名排序（仅JSON/YAML有效）
// 框架适配与扩展
"i18n-ally.enabledFrameworks": ["vue"], // 手动指定适配框架（如Vue/React）
"i18n-ally.namespace": true, // 文件名映射为命名空间（如en/common.json → $t('common.key')）
"i18n-ally.readonly": false // 关闭只读模式以启用编辑
}
常用语言
| Language string | Description |
|---|---|
| zh-CN | 中文（简体） |
| zh-TW | 中文（繁体） |
| en | 英语 |
| en-us | 英语（美国） |
| ja | 日语 |
| ko | 韩语 |
| pt | 葡萄牙语 |
| th | 泰国语 |
