VS Code-i18n Ally国际化插件

前言

本文借鉴：i18n Ally 插件帮你轻松搞定国际化需求-按模块划分i18n Ally 是一款 VS Code 插件，它能通过可视 - 掘金
本来是没有准备将I18n Ally插件单独写一个博客的，但是了解过后，功能强大，使用方便，解决了很多编码痛点，所以在这里单独写一篇使用的步骤和方法
我这里大概列了如下一些优点
可以直观的看到真实文案，在组件内即可直接看到，无需取对应语言文件内查看原文！！！
可以智能检测并定位语言文件内未找到的key，避免漏翻译
可以直接在VS Code工具中翻译对应的语言，而无需单独去翻译网站搜索，并且会自动生成key名，无需自己起名，并且不仅可以单独翻译词语，还可以翻译整个文件批量翻译、文件夹批量翻译
还可以统计各个语言的翻译进度

我如下演示是基于pnpm + vue3 + I18n演示(当前最新技术比较流行)
Vue I18n官网：Vue I18n

安装

该插件是VS Code的一个插件，在左侧工具栏->扩展里面搜索I18n Ally安装即可

在这里插入图片描述

前置框架搭建

1、新建项目

这里我就不演示了，使用pnpm create vite创建vite项目即可

2、安装引入`I18n`

2.1、安装

pnpm add vue-i18n@10

2.2、新建目录

src->locales目录
src->locales->en.ts文件，根据自己项目语言来，文件名可以自行更改，也可以使用json文件
src->locales->zh-CH.ts文件，根据自己项目语言来，文件名可以自行更改，也可以使用json文件
src->locales->index.ts文件，作为目录主文件，暴露出去配置供main.ts文件引入
注意，上面ts文件最好改成.json文件！！因为这个插件对json、yaml支持可读可写，但是对js、ts只支持读

在这里插入图片描述

`index.ts`

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

export default createI18n({
  locale: 'zh', // 要本地化的 Vue 应用程序的语言
  fallbackLocale: 'zh', // 语言中找不到翻译 API 中指定的密钥资源时要回退到的语言
  messages: {
    en,
    zh
  }
})

2.3、`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')

2.4、测试

可以自行在src->locales/xx.ts文件中添加字段测试

在这里插入图片描述

启动项目查看是否打印中文，因为上面配置的locale: 'zh'默认语言是中文

在这里插入图片描述

3、文件名格式

各地区的文件名是有规范的，组件内会默认根据文件名查找文件，所以文件名最好依照如下来

英文 : en
美国 : en_US
中国 : zh_CN
台湾：zh_TW
香港 : zh_HK
日本 : ja_JP
秘鲁 : es_PE
巴拿马 : es_PA
波斯尼亚和黑山共和国 : sr_BA
危地马拉 : es_GT
阿拉伯联合酋长国 : ar_AE
挪威 : no_NO
阿尔巴尼亚 : sq_AL
伊拉克 : ar_IQ
也门 : ar_YE
葡萄牙 : pt_PT
塞浦路斯 : el_CY
卡塔尔 : ar_QA
马其顿王国 : mk_MK
瑞士 : de_CH
芬兰 : fi_FI
马耳他 : en_MT
斯洛文尼亚 : sl_SI
斯洛伐克 : sk_SK
土耳其 : tr_TR
沙特阿拉伯 : ar_SA
英国 : en_GB
塞尔维亚及黑山 : sr_CS
新西兰 : en_NZ
挪威 : no_NO
立陶宛 : lt_LT
尼加拉瓜 : es_NI
爱尔兰 : ga_IE
比利时 : fr_BE
西班牙 : es_ES
黎巴嫩 : ar_LB
加拿大 : fr_CA
爱沙尼亚 : et_EE
科威特 : ar_KW
塞尔维亚 : sr_RS
美国 : es_US
墨西哥 : es_MX
苏丹 : ar_SD
印度尼西亚 : in_ID
乌拉圭 : es_UY
拉脱维亚 : lv_LV
巴西 : pt_BR
叙利亚 : ar_SY
多米尼加共和国 : es_DO
瑞士 : fr_CH
印度 : hi_IN
委内瑞拉 : es_VE
巴林 : ar_BH
菲律宾 : en_PH
突尼斯 : ar_TN
奥地利 : de_AT
荷兰 : nl_NL
厄瓜多尔 : es_EC
台湾地区 : zh_TW
约旦 : ar_JO
冰岛 : is_IS
哥伦比亚 : es_CO
哥斯达黎加 : es_CR
智利 : es_CL
埃及 : ar_EG
南非 : en_ZA
泰国 : th_TH
希腊 : el_GR
意大利 : it_IT
匈牙利 : hu_HU
爱尔兰 : en_IE
乌克兰 : uk_UA
波兰 : pl_PL
卢森堡 : fr_LU
比利时 : nl_BE
印度 : en_IN
西班牙 : ca_ES
摩洛哥 : ar_MA
玻利维亚 : es_BO
澳大利亚 : en_AU
新加坡 : zh_SG
萨尔瓦多 : es_SV
俄罗斯 : ru_RU
韩国 : ko_KR
阿尔及利亚 : ar_DZ
越南 : vi_VN
黑山 : sr_ME
利比亚 : ar_LY
白俄罗斯 : be_BY
以色列 : iw_IL
保加利亚 : bg_BG
马耳他 : mt_MT
巴拉圭 : es_PY
法国 : fr_FR
捷克共和国 : cs_CZ
瑞士 : it_CH
罗马尼亚 : ro_RO
波多黎哥 : es_PR
加拿大 : en_CA
德国 : de_DE
卢森堡 : de_LU
阿根廷 : es_AR
马来西亚 : ms_MY
克罗地亚 : hr_HR
新加坡 : en_SG
阿曼 : ar_OM
泰国 : th_TH
瑞典 : sv_SE
丹麦 : da_DK
洪都拉斯 : es_HN

使用

1、配置

不管你是像上面创建的新项目，还是基于已经包含I18n的项目并且语言文件都已经配置完成了，再使用扩展的。那么安装完扩展以后，VS Code右下角可以能会提示

我们只需要进入项目.vscode/settings.json文件，添加如下配置即可，文件内原来有的则进行修改
{
  "i18n-ally.localesPaths": [
    "src/locales" // I18n所有语言 所在目录
  ],
  "i18n-ally.enabledParsers": ["ts", "json"] // 解析的文件后缀
}

2、文件`$t('xxx.xxx')`语法自动转换显示

2.1、默认显示`en`文件

这时候我们打开一个使用到国际化($t('xxx'))的vue文件，然后我们就可以看到在使用到的地方会自动转换为在zh-CN.ts配置的内容，将如下显示

可以发现，我的代码为$t('common')，如果这么看的话，什么也看不出来，开发将增加困难。但是插件会自动去locales目录中找en文件，并且替换显示(只是显示，并不修改代码)，这样我们就跟写原来的中/英文一样，没有增加丝毫开发难度

当我们鼠标定位到这一行，它又会转为源代码，让我们继续编辑

2.2、修改默认显示`中文(zh-CN)`文件

我们只需要在.vscode/settings.json中，添加如下内容即可修改默认显示文件
// 设置当前显示的主体语言: zh-CN/en/zh-TW/...
  "i18n-ally.displayLanguage": "zh-CN",
修改完以后，我们再次打开App.vue文件即可看到展示的为中文

在这里插入图片描述

3、自动翻译

注意：批量翻译的话，要注意Vue3中的 template中使用$t('xxx')和<script setup>语法躺中写法不一样，批量的话智能生成一种写法，所以如果vue2的话，会智能在template中使用$t()，在script中使用this.$t()，但是vue3中除非使用选项式API，否则不能使用this关键字

翻译的话，总共需要两步
1.现提取文件内中文到当前显示的zh-CN.json中
2.然后再将提取的内容批量翻译到其他语言文件中

由于最终将提取的文案翻译到其他文件中的步骤一模一样，所以我放到3.4里面了，3.1-3.3全部为提取步骤

3.1、单个词语提取文案

注意，我们要将语言文件改为xxx.json格式，因为插件支持如下

我这里script中的数据写死了，正常是后端返回的，所以对这块咱们就不翻译了，只翻译template中的中文即可

<template>
  <div class="app">
    <div>用户信息：</div>
    <div>用户名：{{ user.name }}</div>
    <div>年龄：{{ user.age }}</div>
    <div>性别：{{ user.gender }}</div>
    <div>电话：{{ user.phone }}</div>
  </div>
</template>

<script setup lang="ts">
import { reactive } from "vue";

const user = reactive({
  name: "张三",
  age: 18,
  gender: "男",
  phone: "1234567890",
});
</script>

<style scoped></style>

我们这时候先鼠标定位到需要翻译的App.vue内，然后打开左侧菜单栏i18n Ally图标，查看待翻译的中文

方法一：点击左侧图标即可

在这里插入图片描述

方法二：鼠标放到待翻译的文字上，点击快速修复，提取文案到i18n，即可

在这里插入图片描述

选择生成的key名称，一般默认使用拼音回车即可

在这里插入图片描述

替换格式，在vue3 + template中，我们一般使用第一个，回车即可

在这里插入图片描述

然后顶部选择存储文件地址

注意：zh-CN的绝对路径，类似C:\A-workSoftWare\code\QianTai\vite-all-01\src\locales\zh-CN.json

在这里插入图片描述

提取效果如下

在这里插入图片描述

3.2、文件批量提取文案

我们要先把光标定位到需要翻译的文件中，然后在左侧菜单栏中右键Hard coded strings [beta]，选择Extract all hard-coded strings (experimental)

在这里插入图片描述

然后顶部选择生成文件地址

注意：zh-CN的绝对路径，类似C:\A-workSoftWare\code\QianTai\vite-all-01\src\locales\zh-CN.json

在这里插入图片描述

提取效果，还智能的使用了数组参数方法，并且观察右侧文件显示的内容智能替换了，鼠标定位上去会显示源码

在这里插入图片描述

3.3、目录批量提取文案

我们在components中创建两个测试组件，非常简单
然后右键目录，选择Extract all hard-coded strings (experimental)
你可能没执行过上面选择生成文件名、文件目录配置，有可能会在顶部弹出来让你选择，我这里没有弹框，直接替换的

在这里插入图片描述

效果如下

在这里插入图片描述

3.4、翻译前申请

由于我们下面使用的是百度翻译API，所以我们要先进入官网，再官网申请api权限，步骤如下

进入开放平台官网百度翻译开放平台

往下翻，选择通用文本翻译

选择立即使用

申请完以后，右上角进入选择开发者信息

然后将自己申请信息中的APP ID、密钥，分别粘贴到.vscode->settings.json文件的i18n-ally.translate.baidu.appid、i18n-ally.translate.baidu.apiSecret中

修改完上面后，我们点击下面的修改服务信息

翻到下面，将自己要调用api(本地电脑)的外网IP粘贴进来

不知道的话可以访问IP地址查询_本机IP_我的IP，查询

3.5、将文案翻译到其他文件

上面3.4的前置步骤做完以后，我们进入如下配置

组件默认的翻译是google，我们可以修改其他翻译源，以下是可以选择的翻译源

注意，也要在.vscode->settings.json中添加如下配置，如果少了哪个，注意添加下
"i18n-ally.translate.engines": ["baidu"], // 翻译器，第一个不行会尝试后面的
// 插件将以何种语言作为基准来进行翻译相关的操作，如果你正在开发一个多语言应用，并且原始文案是用英语编写的，你可以将`sourceLanguage`设置为`en`（代表英语）。这样，插件就知道在提取文案进行翻译或者在代码中关联不同语言的文案时，以英语文案为原始参考。
"i18n-ally.translate.baidu.appid": "你在百度申请的appid", // 翻译器api-appid
"i18n-ally.translate.baidu.apiSecret": "你在百度申请的appSecret", // 翻译器api-Secret
"i18n-ally.sourceLanguage": "zh-CN",
"i18n-ally.keystyle": "nested", // 翻译路径格式 (翻译后变量格式 nested：嵌套式  flat:扁平式)
点击左侧i18n Ally菜单栏->翻译进度，可以看到中文(100%)，英文(0%)

然后鼠标放到缺失的文案上面，右侧有个互联网图标，点击图标即可批量翻译，也可以放到单个选项上，右侧也可以进行单个翻译

在这里插入图片描述

由于百度api限制QPS(百度翻译 API 对每秒的请求次数有一定限制。如果你的应用在短时间内发送了大量请求，超过了这个限制，就会触发该错误)，所以批量翻译可能会报错，并且翻译成功了一个

我这里未认证，所以每秒限制调用1次

所以下面案例我们一个一个调用接口翻译

在这里插入图片描述

3.5、属性名称生成规则修改

我们可以在.vscode->settings.json中添加如下配置来修改提取文案规则

"i18n-ally.extract.keygenStyle" 规则的值有：

default/kebab-case；拼音+短横杠，如 ming-cheng。

snake_case；拼音+下划线，如 ming_cheng。

camelCase；拼音+驼峰，如 mingCheng。

PascalCase；拼音+驼峰+首字符大写，如 MingCheng。

ALL_CAPS；拼音+下划线+全大写，如 MING_CHENG。

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

在这里插入图片描述

4、快速定位与修改

当我们想要修改某个已经配置过中英文对应的当前语言(中文)的时候，我们不用在cv变量名，打开对应的语言文件，去ctrl + f搜索，然后修改了

我们只需要鼠标放到$t()方法上，然后，就会有如下提示框

第一个图标是打开审阅，第二个是编辑文案，第三个是跳转定义

我们直接点击对应语言的第二个笔的图标，然后在顶部输入修改后的内容，即可自动替换到对应文件中

在这里插入图片描述

5、忽略文案修改

步骤依旧是，鼠标放到中文上，点击快速修复，第一个是在当前文件内忽略这个中文，第二个是全局整个项目忽略

点击任意一个后，查看.vscode->setteings.json文件，可以查看忽略的配置

忽略完以后，再点击左侧工具栏-> Hard coded strings [beta]就没有这两个需要生成的选项了，对应的组件中，黄色下划线也会消失

6、按模块划分-命名空间

6.1、方法一：

所有的内容都放在对象的一层属性中，会显得杂乱，难以查看，那么我们可以文件命名，比如user.yongHuXinXi等，表示下面属性都属于User页面下

那么我们只需要在顶部输入key的时候，在前面加上xxx.即可

注意：.vscode->settings.json文件的这个配置值"i18n-ally.keystyle": "nested"嵌套格式。如果为flat，将会生成如下格式数据

在这里插入图片描述

6.2、方法二：

上面是将整个项目放入一个xxx.json文件中，只不过使用子属性区分，优化层次结构
下面这种方式是将每一个模块单独放入一个文件夹中，比如你项目有物流模块、生产模块、系统模块、公共语言(可以共用的)

1.修改配置文件

在.vscode->settings.json中添加如下内容

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

2.修改语言文件结构

注意：当在zh-CN目录下新建了一个模块文件(比如common.json)，对应的其他语言目录中也要创建文件，内容为{}即可
语言文件结构要修改为如下

在这里插入图片描述

3.测试

比如我在App.vue中添加了三个按钮新增、修改、删除，那么其他页面基本都会用到这个按钮，那么我就把其他页面都能用到的中文，全放入common.json这个模块中。用户信息也可放入系统模块中，我这里就不演示了

先把文案提取到i18n

剪切掉上方key名

可以发现插件会自动检测，并提示

点击提示，并且将原来生成的key名，粘贴上去，然后回车即可

默认选择第一个，或直接回车即可

然后就可以发现，在src/locales/zh-CN/common.json中，添加了一条数据，App.vue中显示也没问题

翻译步骤跟第3步一样，丝毫不影响

7、演示的`settings.json`文件

我这里放入我上面演示用的.vscode->settings.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",
}