dpl-i18n

如果您使用的是vscode进行代码开发，我们提供了一个 dpl-i18n插件来辅助您进行项目的国际化开发。

基本功能（中文翻译相关）

1. 中文注释翻译

此外，插件提供检测中文注释的功能，并将检测的中文注释以表格形式展示，用户可自行选择人工翻译或API翻译，并在源文件中将中文注释替换成英文注释。

插件采用正则表达式和抽象语法树（AST）两种方式解析获取代码中的中文注释。其中正则表达式方式支持任何开发语言，可通过配置项 comment.regexp自定义配置不同语言的正则表达式。而抽象语法树方式仅支持前端项目中的.js|.ts|.jsx|.tsx文件。使用方式分别如下：

• 正则表达式匹配：右击侧边栏的文件/文件夹 或 右击编辑器中打开的文件 -> DPL中文翻译 -> 中文注释翻译
• 抽象语法树匹配：右击侧边栏的文件/文件夹 或 右击编辑器中打开的文件 -> DPL中文翻译 -> 中文注释翻译(js/ts)

点击后会将匹配到的中文注释呈现在如下页面中：

详细介绍 ：

• 人工翻译：用户手动输入翻译结果，需要保证输入内容的注释格式与原注释相同，因为点击保存后替换的是输入框中的内容。此外，翻译结果不能为纯空白字符。
• API 翻译：点击按钮①调用API接口翻译。使用API翻译前必须配置 API Token ，否则无法使用该功能。具体可见 配置项介绍。目前，插件支持百度翻译和必应翻译。
• 批量翻译：调用API接口批量翻译当前文件中检测的所有中文注释。若某项翻译已选中删除（③），那么批量翻译会跳过该项。
• 全部翻译：可调用API接口翻译所有文件中检测出的中文注释。若某项翻译已选中删除（③），那么全部量翻译会跳过该项。
• 注释删除：选中删除（③）的注释项，在点击保存后会在源文件中删除该注释。
• 跳转到源文件：点击按钮②可跳转到注释所在的源文件

点击保存按钮后，插件优先删除选中删除（③）的注释项，然后替换已翻译的注释项。对于未选中删除且未翻译的注释点击保存后不会进行任何修改。

注意：

• 由于eslint规则中会限制每行代码长度，为了防止注释替换过程中违反该规则，插件提供了配置项comment.maxLineLength来控制替换后的注释每行最大长度。
• 当前界面打开过程中若修改源文件内容，会同步更新到该页面。

2. 中文翻译

插件提供检测文件/文件夹中所有中文的功能。与其他功能不同的是，该功能支持所有语言类型的文件，而其他功能仅支持前端项目中的 JS/TS 文件。

此外，该功能和中文注释翻译功能在检测文件夹时会默认过滤资源文件，例如：zh-CN.js、zh-CN.ts、messages_zh.properties、node_modules以及一些图片文件等，用户也可自定义配置需要过滤的文件。具体可见插件配置项ChineseDetection.excludePath。

[ 使用方式 ]：右击侧边栏的文件/文件夹 或 右击编辑器中打开的文件 -> DPL中文翻译 -> 中文翻译

该界面与中文注释类似，操作注意事项可见有关中文注释界面的介绍。

3. 选中文本翻译替换

目前中文翻译功能只能检测出离散的中文，例如"文本长度不能超过500字"，检测出的中文是"文本长度不能超过"和"字"两项。对此，插件提供自定义选中文本（包含中文）一键翻译并替换。

基本功能（国际化相关）

1. 替换文案为国际化调用

当您在开发过程中需要将代码某些中文文案替换成国际化调用时，您可能需要打开每种语言的国际化文件添加对应的key，并手动修改源代码。为了简化您的操作，该插件可自动提取代码中出现的待国际化中文文案，并提供可视化界面为提取出的文案配置 key，并自动将新配置的可以添加到国际化文件中，以及源代码中的文案替换成国际化调用。

以DPL国际化方案为例，若代码中存在中文文案你好，该功能即提供一种将 你好 替换为 localeText('COMMON.HELLO') 的便捷方式。

其中 localeText() 函数即为国际化调用（不同项目或不同国际化方案使用的函数可能不同）

插件提供了两种将代码中中文文案替换为国际化调用的模式：

• [单文案模式]：当鼠标指针移到待国际化中文文案上方时，会显示配置key按钮。
• [多文案模式]：右击侧边栏的文件/文件夹 或 右击编辑器中打开的文件 -> DPL国际化 -> 中文 [localeText] 替换，可批量替换文件/文件夹中所有中文文案

以上两种模式提取的中文文案会在键值编辑界面展示，用户可为其配置key，点击保存后，会在源文件中将中文文案替换为国际化调用，并在国际化文件中添加配置的key。

键值配置界面详细介绍如下：

• 文件路径(①)：提取的待国际化文案所属文件（相对路径）
• 所属页面(②)：待国际化文案的页面key（一级key），例如：'COMMON.OK' 中的 'COMMON'
• 文案键(③): 标识待国际化文案的key，例如：'COMMON.OK' 中的 'OK'
• 批量设置页面key：点击按钮④可将当前文件所有待国际化文案的页面 key 全部设置为输入框⑤中的内容。
• 重复文案提示：若文案后出现按钮⑥，说明当前文件中存在相同的文案，点击按钮⑥可为所有与当前文案相同的文案配置相同的key。
• 跳转到源文件；点击按钮⑦，可跳转到该文案在源文件中的指定位置。
• 自动生成key：点击按钮⑧，插件会调用Api翻译文案，并用下划线 _ 拼接所有单词大写形式，生成文案的键。

点击保存按钮后，所有同时配置了所属页面(②)和文案键(③)的文案会在源代码中替换成国际化调用，并在国际化文件中加入这些中文文案以及对应的键。

注意：当前界面打开过程中若修改源文件内容，会同步更新到该页面。

2. 查看key所对应的国际化内容

当代码中某些文案替换成国际化调用后，若想知道该国际化调用对应的各语言文案，您可能需要打开对应的国际化文件进行查找。对此，该插件提供了hover显示国际化内容的功能。当鼠标指针移到 key 或国际化方法上方时，会显示该 key 所对应的国际化内容。

hover内容同时提供编辑和跳转的功能：

• 编辑：点击按钮①，可编辑该key对应语言的文案
• 跳转到国际化文件：点击按钮②，可跳转到对应语言国际化文件中该key的所在位置。

此外，插件还支持在编辑器中直接显示key对应的国际化内容。可点击右下角状态栏图标(①)，切换当前编辑器展示的语言。如果选择none，则展示key。

3. 编辑国际化文件

在项目迭代更新过程中，可能需要更新页面上的某些文案，这时就需要打开每个国际化文件进行修改，操作过程繁琐，容易造成遗漏。对此，插件提供以表格形式展示国际化文件中的所有 key 以及对应的各国语言文案，且用户可在该界面编辑每个 key 对应的文案。

[ 使用方式 ]：

• 编辑器中右击 -> DPL国际化 -> 编辑国际化文件
• 打开命令面板（ctrl + shift + p） -> 执行命令 DPL-I18n: Edit locale file

该页面提供了四种视图：

• [全部]：所有国际化文件中出现的key
• [未翻译]：除中文外，存在其他语言未翻译的 key。
• [缺失项]：仅在部分语言的国际化文件中存在，而其他的国际化文件中不存在的 key。
• [已修改]：已经编辑修改过的key

插件能实时监测项目国际化文件的变化，在状态栏提示当前国际化文件中未翻译和缺失 key。点击状态栏的提示图标(①)，可打开国际化文件编辑界面的未翻译或缺失项视图，对未翻译和缺失 key 的文案进行编辑。

注意：

• 由于项目国际化文件中 key 总数通常较大，故用户修改某些 key 的文案后，可切换到已修改视图查看修改过文案的 key。点击保存按钮后，也仅会保存已修改视图下展示的数据。
• 若用户配置了多个国际化目录，在编辑国际化文件前需选择目录。

4. 检测项目中未使用的 key

由于项目的迭代更新，国际化文件中可能会存在未被使用key。对此，插件提供了检测未使用 key 的功能，用户可自定义删除未使用的key，以保证国际化文件的整洁性。

[ 使用方式 ]：右击侧边栏的文件/文件夹 -> DPL国际化 -> 检测未使用的key

用户可在该界面选择需要删除的key，然后删除。

5. key 自动补全

当我们想要复用某个文案的key时，需要打开国际化文件去查找。对此，插件提供了对已经存在的key自动补全功能。当我们调用国际化方法（例如localeText）时，插件会提示所有已经配置的key。

开始使用

1. 下载vscode插件 dpl-i18n

2. 进行项目配置

"DPL国际化"目录下的功能必须进行项目配置后才能正常使用

注意事项

1. 由于js书写比较灵活，目前国际化文件 zh-CN.js(ts)仅支持如下语法:

module.exports

• 直接导出

module.exports = {
  COMMON: {}
}

• 声明变量导出

const data = {
  COMMON: {}
}
module.exports = data;

export default

• 直接导出

export default {
  COMMON: {}
}

• 声明变量导出

const data = {
  COMMON: {}
}
export default data;

配置

一.项目配置

由于不同项目使用的国际化方法以及存放国际化文件的目录等可能不同，所以不同项目可根据实际代码情况进行配置。(仅需要使用国际化相关功能的项目需要配置)

[ 打开项目配置方式 ]；

• 编辑器中右击 -> DPL国际化 -> 项目配置
• 打开命令面板（ctrl + shift + p） -> 执行命令 DPL-I18n: Project config

具体配置项如下：

1. 基础配置

基础配置是每个使用该插件项目必须配置的。

2. 高级配置

高级配置仅项目需要时才配置。

• 何时需要配置其他国际化目录

例如某些项目的locale文件夹下会有一个message文件夹用于存放和message相关的一些文案。此时便可将message配置到其他国际化目录中。

此外，配置的其他国际化目录仅支持查看key对应的国际化文案、编辑国际化文件、key自动补全等功能。当进行中文localeText替换时，新增的key仍然保存到默认的国际化目录中。

• 何时需要配置页面方法

例如我们在 lang.js 文件中定义了 pageMsg 方法：

export function pageMsg(pageKey) {
  return (key, ...valueArr) => msg(`${pageKey}.${key}`, ...valueArr);
}

然后我们在某个文件中引入了该方法：

import {pageMsg} from 'lang.js';
const commonMsg = pageMsg('common');

那么在该文件中 commonMsg('OK') 等价于 msg('COMMON.OK')，如果希望指针指向 OK 时能够显示国际化内容，那么就需要配置页面方法为pageMsg。

• 何时需要配置自定义页面方法:

例如我们在 langUtil.js 文件中定义了 commonMsg 方法：

import {pageMsg} from '@/common/js/lang';
const commonMsg = pageMsg('common');
export commonMsg;

然后我们在某个文件中引入了commonMsg：

import {commonMsg} from 'langUtil.js';

那么在该文件中 commonMsg('OK') 等价于 msg('COMMON.OK')，如果希望指针指向 OK 时能够显示国际化内容，那么就需要在自定义页面方法中添加 commonMsg。

注意：当配置了页面方法或者自定义页面方法时，替换文案为国际化调用时，会优先使用页面方法替换。

二. 插件配置

插件配置适用于任何使用该插件的项目。

[ 打开插件配置方式 ]：打开 VSCode 设置( ctrk + ,) -> 选择插件 -> 选择 dpl-i18n

具体配置项如下所示：

excludePath 匹配规则

excludePath 采用 minimatch 进行路径匹配，匹配规则简单介绍如下：

• *：匹配 0 个或多个字符。
• ?：匹配1个字符
• [...]：匹配一系列字符，类似于正则表达式的范围。如果范围的第一个字符是 !或 ^ 则匹配不在该范围内的任何字符。如果第一个字符是]，那么它将被视为与]相同，而不是字符类的结尾。
• !(pattern|pattern|pattern)：匹配与所提供的任何模式都不匹配的任何内容。不能包含 / 字符
• ?(pattern|pattern|pattern)：匹配0次或1次出现的所提供的模式。不能包含 / 字符
• +(pattern|pattern|pattern)：匹配所提供的模式的1次或多次出现。不能包含 / 字符
• *(a|b|c) 匹配所提供模式的零次或多次出现。不得包含 / 字符
• @(pattern|pat*|pat?erN)：完全匹配所提供的模式之一。不能包含 / 字符。
• **：匹配0到多个子目录，递归匹配子目录