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

本文详解 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插件

shell 复制代码

npm install vue-i18n@next
pnpm install vue-i18n@next
yarn add vue-i18n@next

二、vue3工程配置

1.创建i18n入口文件

ts 复制代码

//语言
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

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

json 复制代码

 {
  "desc": "登录",
  "form_auto": "自动登录",
  "form_button": "登录",
  "login_success": "登录成功",
  "login_message": "请填写完整信息"
}

i18n/zh/index.ts

typescript 复制代码

import login from './login.json'
const global = {
  // 系统设置
  sys_set: '系统设置',
  contact: '关于软件',
  logout: '退出登录',
}

export default {
  global,
  login
}

整体结构

3.main.js导入i18n依赖

ts 复制代码

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 ，可以根据自己的文件路径修改。

我的文件路径是嵌套结构所以需要启用命名空间

json 复制代码

"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

json 复制代码

"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 中添加或修改以下配置：

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）

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	泰国语