国际化（i18n）开发指南

国际化（Internationalization，简称 i18n）是让应用支持多语言的关键技术。本文档介绍 Vue 项目的国际化方案及相关工具配置。

资源	说明	链接
vue-i18n	Vue 官方多语言解决方案	文档
i18n Ally	VS Code 多语言插件，提升开发效率	插件市场
可视化操作教程	详细的插件使用教程	参考文档

i18n Ally 插件优势

可以直观的看到真实文案，在组件内即可直接看到，无需取对应语言文件内查看原文！
可以智能检测并定位语言文件内未找到的 key，避免漏翻译
可以直接在 VS Code 工具中翻译对应的语言，而无需单独去翻译网站搜索，并且会自动生成 key 名，无需自己起名，并且不仅可以单独翻译词语，还可以翻译整个文件批量翻译、文件夹批量翻译

关于 i18n Ally 可视化操作可以查看参考文档

vue-i18n 快速入门

环境要求

Vue 3
TypeScript（推荐）
包管理器：pnpm / npm / yarn

安装

bash

# pnpm
pnpm add vue-i18n

# npm
npm install vue-i18n

# yarn
yarn add vue-i18n

项目结构

推荐的多语言文件组织方式：

src/
└── locales/
    ├── index.ts      # 入口配置
    ├── en.ts         # 英文（或 en.json）
    └── zh.ts         # 中文（或 zh.json）

文件格式选择

JSON：简单直观，适合小型项目
TypeScript：支持类型检查，适合大型项目（需要额外配置）

配置入口（index.ts）

import { createI18n } from "vue-i18n";
import en from "./en";
import zh from "./zh";

export default createI18n({
  locale: "zh",           // 默认语言
  fallbackLocale: "zh",   // 回退语言（当找不到翻译时使用）
  messages: {
    en,
    zh,
  },
});

配置项	说明
`locale`	当前使用的语言
`fallbackLocale`	回退语言，当当前语言缺少翻译时使用
`messages`	语言包对象

main.ts 写法

import { createApp } from "vue";
import "./style.css";
import App from "./App.vue";
// 重要
import I18n from "@/locales";
const app = createApp(App);
app.use(I18n);
app.mount("#app");

en.ts / zh.ts 写法

如果是 json 写法的话，去掉 export default 即可

export default {
  common: {
    confirm: "确认",
  },
};

页面使用

template 区域

vue

<template>
  <div>
    {{ $t("common.confirm") }}
  </div>
</template>

script 区域

//

i18n Ally VSCode 配置

基础配置

操作 vscode 工作区 .vscode/settings.json

json

{
  "i18n-ally.localesPaths": [
    "src/locales" // I18n所有语言 所在目录
  ],
  "i18n-ally.enabledParsers": ["ts", "json"] // 解析的文件后缀
}

默认语言版本配置

文件$t('xxx.xxx')语法自动转换显示，默认显示en文件，修改默认显示中文zh文件

操作工作区配置.vscode/settings.json

新增如下配置

json

// 设置当前显示的主体语言: zh-CN/en/zh-TW/...
"i18n-ally.displayLanguage": "zh-CN",

属性名生成规则配置

操作工作区设置.vscode->settings.json

json

// 翻译文案的属性名称策略：slug-拼音、random-随机、empty-需要手动命名
"i18n-ally.extract.keygenStrategy": "slug",
// 属性名称的具体生成规则 驼峰
"i18n-ally.extract.keygenStyle": "camelCase",

可选配置值如下

default/kebab-case: 拼音+短横杠，如 js-pao。 snake_case: 拼音+下划线，如 js_pao。 camelCase: 拼音+驼峰，如 jsPao PascalCase: 拼音+驼峰+首字符大写，如 JsPao。 ALL_CAPS: 拼音+下划线+全大写，如 JS_PAO。

命名空间 (按模块划分)

操作工作区配置文件 .vscode->settings.json

方法一: 嵌套格式或扁平键格式

json

"i18n-ally.keystyle": "nested" // 嵌套格式，flat 为 扁平化翻译键 (扁平键格式/点分表示法)

嵌套格式 nested

json

{
  "common": {
    "confirm": "确认"
  }
}

扁平化翻译键 (扁平键格式/点分表示法) flat

json

{
  "common.confirm": "确认"
}

方法二：模块化语言包

json

// 使用空间命名
"i18n-ally.namespace": true,
"i18n-ally.pathMatcher": "{locale}/{namespace}.json",

语言结构如下

- src
    - locales
        - en
            - common.json
            - index.ts
        - zh
            - common.json
            - index.ts
        - index.ts

en / zh index.ts 写法

json 依然保持 嵌套格式 或者 扁平化翻译键

import common from "./common.json";
import user from "./user.json";
export default {
  common,
  user,
};

完整的工作区配置

json

{
  // 设置当前显示的主体语言: zh-CN/en/zh-TW/...
  "i18n-ally.displayLanguage": "zh-CN",
  // 插件将以何种语言作为基准来进行翻译相关的操作，如果你正在开发一个多语言应用，并且原始文案是用英语编写的，你可以将`sourceLanguage`设置为`en`（代表英语）。这样，插件就知道在提取文案进行翻译或者在代码中关联不同语言的文案时，以英语文案为原始参考。
  "i18n-ally.sourceLanguage": "zh-CN",
  "i18n-ally.localesPaths": [
    // 翻译文件夹路径 (相对于项目根目录)，你也可以使用Glob匹配模式。
    "src/locales"
  ],
  "i18n-ally.translate.engines": ["baidu"], // 指定翻译器
  "i18n-ally.translate.baidu.appid": "你的appid", // 翻译器api-appid
  "i18n-ally.translate.baidu.apiSecret": "你的appSecret", // 翻译器api-Secret
  "i18n-ally.enabledParsers": [
    // 指定启用文件格式
    "json",
    "yaml"
  ],
  "i18n-ally.keystyle": "nested", // 翻译路径格式 (翻译后变量格式 nested：嵌套式  flat:扁平式)
  // ...
  // 翻译文案的属性名称策略：slug-拼音、random-随机、empty-需要手动命名
  "i18n-ally.extract.keygenStrategy": "slug",
  // 属性名称的具体生成规则 驼峰
  "i18n-ally.extract.keygenStyle": "camelCase",
  "i18n-ally.enabledFrameworks": ["vue"],
  // 使用空间命名
  "i18n-ally.namespace": true,
  "i18n-ally.pathMatcher": "{locale}/{namespace}.json"
}

常用语言代码参考

主要语言代码

语言	代码	地区代码示例
简体中文	`zh` / `zh-CN`	中国：`zh-CN`
繁体中文	`zh-TW` / `zh-HK`	台湾：`zh-TW`，香港：`zh-HK`
英语	`en`	美国：`en-US`，英国：`en-GB`
日语	`ja` / `ja-JP`	日本：`ja-JP`
韩语	`ko` / `ko-KR`	韩国：`ko-KR`
法语	`fr`	法国：`fr-FR`，加拿大：`fr-CA`
德语	`de`	德国：`de-DE`，奥地利：`de-AT`
西班牙语	`es`	西班牙：`es-ES`，墨西哥：`es-MX`
俄语	`ru` / `ru-RU`	俄罗斯：`ru-RU`
葡萄牙语	`pt`	葡萄牙：`pt-PT`，巴西：`pt-BR`
意大利语	`it` / `it-IT`	意大利：`it-IT`
阿拉伯语	`ar`	阿联酋：`ar-AE`，沙特：`ar-SA`
泰语	`th` / `th-TH`	泰国：`th-TH`
越南语	`vi` / `vi-VN`	越南：`vi-VN`

语言/地区	代码
阿尔巴尼亚	`sq-AL`
白俄罗斯	`be-BY`
保加利亚	`bg-BG`
克罗地亚	`hr-HR`
捷克	`cs-CZ`
丹麦	`da-DK`
爱沙尼亚	`et-EE`
芬兰	`fi-FI`
希腊	`el-GR`
匈牙利	`hu-HU`
冰岛	`is-IS`
爱尔兰	`ga-IE`
拉脱维亚	`lv-LV`
立陶宛	`lt-LT`
马其顿	`mk-MK`
荷兰	`nl-NL`
挪威	`no-NO`
波兰	`pl-PL`
罗马尼亚	`ro-RO`
塞尔维亚	`sr-RS`
斯洛伐克	`sk-SK`
斯洛文尼亚	`sl-SI`
瑞典	`sv-SE`
土耳其	`tr-TR`
乌克兰	`uk-UA`

国际化（i18n）开发指南

相关资源

i18n Ally 插件优势

vue-i18n 快速入门

环境要求

安装

项目结构

配置入口（index.ts）

main.ts 写法

en.ts / zh.ts 写法

页面使用

template 区域

script 区域

i18n Ally VSCode 配置

基础配置

默认语言版本配置

属性名生成规则配置

命名空间 (按模块划分)

方法一: 嵌套格式或扁平键格式

方法二：模块化语言包

完整的工作区配置

常用语言代码参考

主要语言代码

更多语言代码

国际化（i18n）开发指南 ​

相关资源 ​

i18n Ally 插件优势 ​

vue-i18n 快速入门 ​

环境要求 ​

安装 ​

项目结构 ​

配置入口（index.ts） ​

main.ts 写法 ​

en.ts / zh.ts 写法 ​

页面使用 ​

template 区域 ​

script 区域 ​

i18n Ally VSCode 配置 ​

基础配置 ​

默认语言版本配置 ​

属性名生成规则配置 ​

命名空间 (按模块划分) ​

方法一: 嵌套格式或扁平键格式 ​

方法二：模块化语言包 ​

完整的工作区配置 ​

常用语言代码参考 ​

主要语言代码 ​

更多语言代码 ​

国际化（i18n）开发指南

相关资源

i18n Ally 插件优势

vue-i18n 快速入门

环境要求

安装

项目结构

配置入口（index.ts）

main.ts 写法

en.ts / zh.ts 写法

页面使用

template 区域

script 区域

i18n Ally VSCode 配置

基础配置

默认语言版本配置

属性名生成规则配置

命名空间 (按模块划分)

方法一: 嵌套格式或扁平键格式

方法二：模块化语言包

完整的工作区配置

常用语言代码参考

主要语言代码

更多语言代码