命令行工具
@voerkai18n/cli命令行工具用来实现工程初始化、扫描提取文本、自动翻译和编译语言等功能。
提示
建议将@voerkai18n/cli命令行工具安装在全局
安装
全局安装@voerkai18n/cli工具。
javascript
> npm install -g @voerkai18n/cli
> yarn global add @voerkai18n/cli
> pnpm add -g @voerkai18n/cli然后就可以执行：
javascript
> voerkai18n init
> voerkai18n extract
> voerkai18n compile如果没有全局安装，则需要：
javascript
> yarn voerkai18n init
> yarn voerkai18n extract
> yarn voerkai18n compile
---
> pnpm voerkai18n init
> pnpm voerkai18n extract
> pnpm voerkai18n compile初始化 - init
用于在指定项目创建voerkai18n国际化配置文件。
shell
> voerkai18n init --help
初始化项目国际化配置
Arguments:
location 工程项目所在目录
Options:
-D, --debug 输出调试信息
-r, --reset 重新生成当前项目的语言配置
-m, --moduleType [types] 输出模块类型,取值auto(默认),esm,cjs
-lngs, --languages <languages...> 支持的语言列表 (default: ["zh","en"])
-t, --typescript 输出typescript代码
-d, --defaultLanguage 默认语言
-a, --activeLanguage 激活语言
-h, --help display help for command使用方法如下：
首先需要在工程文件下运行voerkai18n init命令对当前工程进行初始化。
javascript
//- `lngs`参数用来指定拟支持的语言名称列表
> voerkai18n init . -lngs zh en jp de -d zh运行voerkai18n init命令后，会在当前工程中创建相应配置文件。
- languages 多语言目录
- settings.json
- index.js|ts
- idMap.js|ts
- index.md
- package.json
settings.json文件很简单，主要是用来配置要支持的语言等基本信息。
javascript
module.exports = {
// 拟支持的语言列表
"languages": [
{
"name": "zh",
"title": "中文",
// 默认语言，即准备在源码中写的语言，一般我们可以直接使用中文
"default":true,
// 激活语言，即默认要启用的语言，一般等于defaultLanguage
"active":true
},
{
"name": "en",
"title": "英文"
}
],
// 翻译名称空间定义，详见后续介绍。
"namespaces": {}
}说明：
如果你的源码放在
src文件夹，则init命令会自动在在src文件夹下创建languages文件夹。-m参数用来指定生成的settings.json的模块类型：- 当
-m=auto时，会自动根据前工程package.json中的type字段等信息来决定源码的模块类型 - 当
-m=esm时，会生成ESM模块类型的settings.json。 - 当
-m=cjs时，会生成commonjs模块类型的settings.json。
- 当
location参数是可选的，如果没有指定则采用当前目录。voerkai18n init能识别当前是否是typescript工程，方法是通过检查是否存在tsconfig.json来判断。也可以显式指定voerkai18n init --typescript来生成对应的typescript源码。如果你想将
languages安装在src/languages下，则可以指定voerkai18n init ./src生成在
idMap文件是一个空文件，后续会自动更新，不需要修改。index.(js|ts)也是一个占位文件，后续执行compile时会覆盖重新生成
提取文本 - extract
扫描提取当前项目中的所有源码，提取出所有需要翻译的文本内容并保存在到<工程源码目录>/languages/translates/*.json。
shell
> voerkai18n extract --help
扫描并提取所有待翻译的字符串到<languages/translates>文件夹中
Arguments:
location 工程项目所在目录 (default: "./")
Options:
-D, --debug 输出调试信息
-lngs, --languages 支持的语言
-d, --defaultLanguage 默认语言
-a, --activeLanguage 激活语言
-ns, --namespaces 翻译名称空间
-e, --exclude <folders> 排除要扫描的文件夹，多个用逗号分隔
-u, --updateMode 本次提取内容与已存在内容的数据合并策略,默认取值sync=同步,overwrite=覆盖,merge=合并
-f, --filetypes 要扫描的文件类型
-h, --help display help for command说明：
- 启用
-d参数时会输出提取过程，显示从哪些文件提取了几条信息。 - 如果已手动创建或通过
init命令创建了languages/settings.json文件，则可以不指定-ns，-lngs，-d，-a参数。extract会优先使用languages/settings.json文件中的参数来进行提取。 -u参数用来指定如何将提取的文本与现存的文件进行合并。因为在国际化流程中，我们经常面临源代码变更时需要更新翻译的问题。支持三种合并策略。- sync：同步（默认值）,两者自动合并，并且会删除在源码文件中不存在的文本。如果某个翻译已经翻译了一半也会保留。此值适用于大部情况，推荐。
- overwrite：覆盖现存的翻译内容。这会导致已经进行了一半的翻译数据丢失，慎用。
- merge：合并，与sync的差别在于不会删除源码中已不存在的文本。
-e参数用来排除扫描的文件夹，多个用逗号分隔。内部采用gulp.src来进行文件提取，请参数。如-e !libs,core/**/*。默认会自动排除node_modules文件夹-f参数用来指定要扫描的文件类型，默认js,jsx,ts,tsx,vue,htmlextract是基于正则表达式方式进行匹配的，而不是像i18n-next采用基于AST解析。
重点：
默认情况下，
voerkai18n extract可以安全地反复多次执行，不会导致已经翻译一半的内容丢失。如果想添加新的语言支持，也
voerkai18n extract也可以如预期的正常工作。
自动翻译 - translate
在工程文件夹下执行voerkai18n translate命令，该命令会读取languages/settings.json配置文件，并调用在线翻译服务（如百度在线翻译）对提取的文本(languages/translates/*.json)进行自动翻译。
shell
Usage: voerkai18n translate [options] [location]
调用在线翻译服务商的API翻译译指定项目的语言包,如使用百度云翻译服务
Arguments:
location 工程项目所在目录
Options:
-p, --provider <value> 在线翻译服务提供者名称或翻译脚本文件 (default: "baidu")
-m, --max-package-size <value> 将多个文本合并提交的最大包字节数 (default: 3000)
--appkey [key] API密钥
--appid [id] API ID
--no-backup 备份原始文件
--mode 翻译模式，取值auto=仅翻译未翻译的,full=全部翻译
-q, --qps <value> 翻译速度限制,即每秒可调用的API次数 (default: 1)
-h, --help 显示帮助内置支持调用百度的在线翻译服务，您需要百度的网站上(http://api.fanyi.baidu.com/)申请开通服务，开通后可以得到
appid和appkey（密钥）。--provider用来指定在线翻译服务提供者，内置支持的是百度在线翻译。也可以传入一个js脚本，如下：javascript// youdao.js module.exports = async function(options){ let { appkey,appid } = options return { translate:async (texts,from,to){ // texts是一个Array // from,to代表要从哪一种语言翻译到何种语言 ..... // 在此对texts内容调用在线翻译API // 翻译结果应该返回与texts对应的数组 // 如果出错则应该throw new Error() return [...] } } }qps用来指定调用在线翻译API的速度，默认是1，代表每秒调用一次；此参数的引入是考虑到有些翻译平台的免费API有QPS限制。比如百度在线翻译免费版本限制QPS就是1，即每秒只能调用一次。如果您购买了服务，则可以将QPS调高。默认情况下，每次运行时均会备份原始的翻译文件至
languages/translates/backup，--no-backup可以禁止备份。默认情况下，
voerkai18n translate会在每次运行时跳过已经翻译过的内容，这样可以保留翻译成果。此特性在您对自动翻译的内容进行修改后，再多次运行voerkai18n translate命令时均能保留翻译内容，不会导致您修改调整过的内容丢失。--mode full参数可以完全覆盖翻译，请慎用。为了提高在线翻译的速度，
voerkai18n translate并不是一条文本调用一次API，而是将多条文本合并起来进行调用，但是单次调用也是有数据包大小的限制的，--max-package-size参数用来指定数据包的最大值。比如百度建议，为保证翻译质量，请将单次请求长度控制在 6000 bytes以内（汉字约为输入参数 2000 个）。需要注意的是，自动翻译虽然准确性还不错，真实场景还是需要进行手工调整的，特别是自动翻译一般不能识别插值变量。
自动翻译不支持对复数形式的内容进行翻译，需要手工进行翻译
编译 - compile
编译当前工程的语言包，编译结果输出在./langauges文件夹。
shell
Usage: voerkai18n compile [options] [location]
编译指定项目的语言包
Arguments:
location 工程项目所在目录 (default: "./")
Options:
-D, --debug 输出调试信息
-l, --library 开发库模式(default:false)
-t, --typescript 生成typescript文件
-u, --update-runtime 自动更新runtime
--skip 跳过更新language/index.(ts|js)文件(default:false)
-h, --help display help for commandvoerkai18n compile执行后会在langauges文件夹下输出：
- languages
- settings.json
- index.js|ts
- idMap.js|ts
- zh.js|ts
- en.js|ts
- xx.js|ts
- storage.js|ts
- formatters
- zh.js|ts
- en.js|ts
- xx.js|ts
多语言
默认情况下,@voerkai18n/cli会尝试读取当前操作系的语言，并使该语言进行显示。如果当前操作系统的语言不在支持的语言列表中，则会使用en作为默认语言。
- 可以通过
--lang参数来指定默认的语言，比如voerkai18n --lang zh。 - 可以通过环境变量
set LANGUAGE=xx来指定默认的语言，比如set LANGUAGE=zh & voerkai18n extract。
说明：
- 在当前工程目录下，一般不需要指定参数就可以反复多次进行编译。
- 您每次修改了源码并
extract后，均应该再次运行compile命令。 - 如果您修改了
formatters.js，执行compile命令不会重新生成和修改该文件。 - 默认情况下，
compile命令当发现当前工程存在ts.config.ts时，会生成languages/**/*.ts。也可以显式指定voerkai18n compile --typescript来生成ts源码，或者显式指定voerkai18n compile --typescript=false来禁用生成ts源码。 - 注意，
compile命令会重新覆盖languages/index.(js|ts),如果您修改了该文件，而不希望被覆盖，请指定--skip参数。