Vue3国际化开发实战：i18n-Ally + vue-i18n@next高效配置教程，项目中文显示

本文详解 Vue3 国际化开发全流程：从安装 vue-i18n@next 到配置多语言文件（JSON/YAML），结合 i18n-Ally 插件实现高效翻译管理。重点涵盖：

1. 工程配置：创建 i18n 实例、模块化语言文件结构（支持命名空间）、注册至 Vue 应用。
2. 插件优化：通过 settings.json 配置路径、键名风格、翻译引擎（Google/DeepL），实现代码内联翻译显示。
3. 避坑指南：关闭只读模式、选择可编辑格式（避免 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	泰国语