新鲜出炉的Nodejs/Vue/React多语言解决方案

前言

基于javascript的国际化方案很多，比较有名的有fbt、i18next、react-i18next、vue-i18n、react-intl等等，每一种解决方案均有大量的用户。为什么还要再造一个轮子？好吧，再造轮子的理由不外乎不满足于现有方案，总想着现有方案的种种不足之处，然后就撸起袖子想造一个轮子，也不想想自己什么水平。

哪么到底是对现有解决方案有什么不满？最主要有三点：

大部份均为要翻译的文本信息指定一个key，然后在源码文件中使用形如$t("message.login")之类的方式，然后在翻译时将之转换成最终的文本信息。此方式最大的问题是，在源码中必须人为地指定每一个key，在中文语境中，想为每一句中文均配套想一句符合语义的英文key是比较麻烦的，也很不直观不符合直觉。我希望在源文件中就直接使用中文，如t("中华人民共和国万岁")，然后国际化框架应该能自动处理后续的一系列麻烦。
要能够比较友好地支持多库多包monorepo场景下的国际化协作，当主程序切换语言时，其他包或库也可以自动切换，并且在开发上每个包或库均可以独立地进行开发，集成到主程序时能无缝集成。这点在现有方案上没有找到比较理想的解决方案。
大部份国际化框架均将中文视为二等公民，大部份情况下您应该采用英文作为第一语言，虽然这不是太大的问题，但是既然要再造一个轮子，为什么不将中文提升到一等公民呢。

基于此就开始造出VoerkaI18n这个全新的国际化多语言解决方案，主要特性包括：

简单易用
符合直觉，不需要手动定义文本Key映射。
完整的自动化工具链支持，包括项目初始化、提取文本、编译语言等。
支持babel插件自动导入t翻译函数。
支持nodejs、浏览器(vue/react)前端环境。
采用工程工具链与运行时分开设计，发布时只需要集成很小的运行时(12K)。
高度可扩展的复数、货币、数字等常用的多语言处理机制。
通过格式化器可以扩展出强大的多语言特性。
翻译过程内，提取文本可以自动进行同步，并保留已翻译的内容。
可以随时添加支持的语言

安装

VoerkaI18n国际化框架是一个开源多包工程，主要由以下几个包组成：

@voerkai18/runtime

必须的运行时，安装到运行依赖dependencies中

npm install --save @voerkai18/runtime
yarn add @voerkai18/runtime
pnpm add @voerkai18/runtime

@voerkai18/cli
包含文本提取/编译等命令行工具，应该安装到开发依赖devDependencies中
```
npm install --save-dev @voerkai18/cli
yarn add -D @voerkai18/cli
pnpm add -D @voerkai18/cli
```
@voerkai18/formatters
可选的，一些额外的格式化器，可以按需进行安装到dependencies中，用来扩展翻译时对插值变量的额外处理。
@voerkai18/babel
可选的babel插件，用来实现自动导入翻译函数和翻译文本映射自动替换。

快速入门

本节以标准的Nodejs应用程序为例，简要介绍VoerkaI18n国际化框架的基本使用。其他vue或react应用的使用也基本相同。

myapp
  |--package.json
  |--index.js

在本项目的所有支持的源码文件中均可以使用t函数对要翻译的文本进行包装，简单而粗暴。

// index.js
console.log(t("中华人民共和国万岁"))
console.log(t("中华人民共和国成立于{}",1949))

t翻译函数是从myapp/languages/index.js文件导出的翻译函数，但是现在myapp/languages还不存在，后续会使用工具自动生成。voerkai18n后续会使用正则表达式对提取要翻译的文本。

第一步：初始化工程

在工程目录中运行voerkai18n init命令进行初始化。

> voerkai18n init

上述命令会在当前工程目录下创建languages/settings.json文件。如果您的源代码在src子文件夹中，则会创建在src/languages/settings.json

settings.json内容如下:

{
    "languages": [
        {
            "name": "cn",
            "title": "cn"
        },
        {
            "name": "en",
            "title": "en"
        }
    ],
    "defaultLanguage": "cn",
    "activeLanguage": "cn",
    "namespaces": {}
}

上述命令代表了：

本项目拟支持中文和英文两种语言。
默认语言是中文(即在源代码中直接使用中文)
激活语言是中文

注意：

voerkai18n init是可选的，voerkai18n extract也可以实现相同的功能。
一般情况下，您可以手工修改settings.json，如定义名称空间。

第二步：提取文本

接下来我们使用voerkai18n extract命令来自动扫描工程源码文件中的需要的翻译的文本信息。

myapp>voerkai18n extract

执行voerkai18n extract命令后，就会在myapp/languages通过生成translates/default.json、settings.json等相关文件。

translates/default.json ：该文件就是需要进行翻译的文本信息。
settings.json：语言环境的基本配置信息，可以进行修改。

最后文件结构如下：

myapp
  |-- languages
    |-- settings.json                // 语言配置文件
    |-- translates                   // 此文件夹是所有需要翻译的内容
      |-- default.json               // 默认名称空间内容
  |-- package.json
  |-- index.js

如果略过第一步中的voerkai18n init，也可以使用以下命令来为创建和更新settinbgs.json

myapp>voerkai18n extract -D -lngs cn en de jp -d cn -a cn

以上命令代表：

扫描当前文件夹下所有源码文件，默认是js、jsx、html、vue文件类型。
计划支持cn、en、de、jp四种语言
默认语言是中文。（指在源码文件中我们直接使用中文即可）
激活语言是中文（即默认切换到中文）
-D代表显示扫描调试信息

第三步：翻译文本

接下来就可以分别对language/translates文件夹下的所有JSON文件进行翻译了。每个JSON文件大概如下：

{
    "中华人民共和国万岁":{
        "en":"<在此编写对应的英文翻译内容>",
        "de":"<在此编写对应的德文翻译内容>"
        "jp":"<在此编写对应的日文翻译内容>",
        "$files":["index.js"]    // 记录了该信息是从哪几个文件中提取的
    },
    "中华人民共和国成立于{}":{
        "en":"<在此编写对应的英文翻译内容>",
        "de":"<在此编写对应的德文翻译内容>"
        "jp":"<在此编写对应的日文翻译内容>",
        "$files":["index.js"]
    }
}

我们只需要修改该文件翻译对应的语言即可。

重点：如果翻译期间对源文件进行了修改，则只需要重新执行一下voerkai18n extract命令，该命令会进行以下操作：

如果文本内容在源代码中已经删除了，则会自动从翻译清单中删除。
如果文本内容在源代码中已修改了，则会视为新增加的内容。
如果文本内容已经翻译了一部份了，则会保留已翻译的内容。

因此，反复执行voerkai18n extract命令是安全的，不会导致进行了一半的翻译内容丢失，可以放心执行。

第四步：编译语言包

当我们完成myapp/languages/translates下的所有JSON语言文件的翻译后（如果配置了名称空间后，每一个名称空间会对应生成一个文件，详见后续名称空间介绍），接下来需要对翻译后的文件进行编译。

myapp> voerkai18n compile

compile命令根据myapp/languages/translates/*.json和myapp/languages/settings.json文件编译生成以下文件：

  |-- languages
    |-- settings.json                // 语言配置文件
    |-- idMap.js                     // 文本信息id映射表
    |-- index.js                     // 包含该应用作用域下的翻译函数等
    |-- cn.js                        // 语言包
    |-- en.js
    |-- jp.js
    |-- de.js
    |-- translates                   // 此文件夹包含了所有需要翻译的内容
      |-- default.json
  |-- package.json
  |-- index.js

第五步：导入翻译函数

第一步中我们在源文件中直接使用了t翻译函数包装要翻译的文本信息，该t翻译函数就是在编译环节自动生成并声明在myapp/languages/index.js中的。

import { t } from "./languages"

因此，我们需要在需要进行翻译时导入该函数即可。但是如果源码文件很多，重次重复导入t函数也是比较麻烦的，所以我们也提供了一个babel插件来自动导入t函数。

第六步：切换语言

当需要切换语言时，可以通过调用change方法来切换语言。

import { i18nScope } from "./languages"

// 切换到英文
await i18nScope.change("en")
// VoerkaI18n是一个全局单例，可以直接访问
VoerkaI18n.change("en")

i18nScope.change与VoerkaI18n.change两者是等价的。

一般可能也需要在语言切换后进行界面更新渲染，可以订阅事件来响应语言切换。

import { i18nScope } from "./languages"

// 切换到英文
i18nScope.on((newLanguage)=>{
    ...
})
// 
VoerkaI18n.on((newLanguage)=>{
    ...
})

指南

翻译函数

默认提供翻译函数t用来进行翻译。一般情况下，t函数在执行voerkai18n compile命令生成在工程目录下的languages文件夹中。


// 从当前语言包文件夹index.js中导入翻译函数
import { t } from "<myapp>/languages"

// 不含插值变量
t("中华人民共和国")

// 位置插值变量
t("中华人民共和国{}","万岁")
t("中华人民共和国成立于{}年，首都{}",1949,"北京")

// 当仅有两个参数且第2个参数是[]类型时，自动展开第一个参数进行位置插值
t("中华人民共和国成立于{year}年，首都{capital}",[1949,"北京"]) 
 
// 当仅有两个参数且第2个参数是{}类型时，启用字典插值变量
t("中华人民共和国成立于{year}年，首都{capital}",{year:1949,capital:"北京"})

// 插值变量可以是同步函数，在进行插值时自动调用。
t("中华人民共和国成立于{year}年，首都{capital}",()=>1949,"北京")

// 对插值变量启用格式化器
t("中华人民共和国成立于{birthday | year}年",{birthday:new Date()})

注意：

voerkai18n使用正则表达式来提取要翻译的内容，因此t()可以使用在任意地方。

插值变量

voerkai18n的t函数支持使用插值变量，用来传入一个可变内容。

插值变量有命名插值变量和位置插值变量。

命名插值变量

可以在t函数中使用{变量名称}表示一个命名插值变量。

t("我姓名叫{name},我今年{age}岁",{name:"tom",age:12})
// 如果值是函数会自动调用
t("我姓名叫{name},我今年{age}岁",{name:"tom",age:()=>12})

仅当t函数仅有两个参数且第2个参数是{}类型时，启用字典插值变量，翻译时会自动进行插值。

位置插值变量

可以在t函数中使用一个空的{}表示一个位置插值变量。

t("我姓名叫{},我今年{}岁","tom",12)
// 如果值是函数会自动调用
t("我姓名叫{},我今年{}岁","tom",()=>12})
// 如果只有两个参数，且第2个参数是一个数组，会自动展开
t("我姓名叫{},我今年{}岁",["tom",12])
//如果第2个参数不是{}时就启用位置插值。
t("我姓名叫{name},我今年{age}岁","tom",()=>12)

插值变量格式化

voerka-i18n支持强大的插值变量格式化机制，可以在插值变量中使用{变量名称 | 格式化器名称 | 格式化器名称(...参数) | ... }类似管道操作符的语法，将上一个输出作为下一个输入，从而实现对变量值的转换。此机制是voerka-i18n实现复数、货币、数字等多语言支持的基础。

格式化器语法

我们假设定义以下格式化器（如果定义格式化器，详见后续）来进行示例。

UpperCase：将字符转换为大写
division：对数字按每n位一个逗号分割，支持一个可选参数分割位数，如division(123456)===123,456，division(123456,4)===12,3456
mr : 自动添加一个先生称呼

// My name is TOM
t("My name is { name | UpperCase }",{name:"tom"})

// 我国2021年的GDP是￥14,722,730,697,890
t("我国2021年的GDP是￥{ gdp | division}",{gdp:14722730697890})

// 支持为格式化器提供参数，按4位一逗号分割
// 我国2021年的GDP是￥14,7227,3069,7890
t("我国2021年的GDP是￥{ gdp | division(4)}",{gdp:14722730697890})

// 支持连续使用多个格式化器
// My name is Mr.TOM
t("My name is { name | UpperCase | mr }",{name:"tom"})

每个格式化器本质上是一个(value)=>{...}的函数，并且能将上一个格式化器的输出作为下一个格式化器的输入，格式化器具有如下特性：

无参数格式化器
使用无参数格式化器时只需传入名称即可。例如:My name is { name | UpperCase }
有参数格式化器
格式化器支持传入参数，如{ gdp | division(4)}、{ date | format('yyyy/MM/DD')}
特别需要注意的是，格式化器的参数只能支持简单的类型的参数，如数字、布尔型、字符串。
不支持数组、对象和函数参数，也不支持复杂的表达式参数。
支持连续使用多个格式化器
就如您预期的一样，将上一个格式化器的输出作为下一个格式化器的输入。
｛data | f1 | f2 | f3(1)｝等效于 f3(f2(f1(data)),1)

自定义格式化器

当我们使用voerkai18n compile编译后，会生成languages/formatters.js文件，可以在该文件中自定义您自己的格式化器。

formatters.js文件内容如下：

module.exports = {
    // 在所有语言下生效的格式化器
    "*":{ 
        //[格式化名称]:(value)=>{...},
        //[格式化名称]:(value,arg)=>{...},
    },                                                
    // 在所有语言下只作用于特定数据类型的格式化器   
    $types:{
        // [数据类型名称]:(value)=>{...},
        // [数据类型名称]:(value)=>{...},
    },                                          
    cn:{
        $types:{
            // 所有类型的默认格式化器
            "*":{                
            },
            Date:{},
            Number:{},
            Boolean:{ },
            String:{},
            Array:{

            },
            Object:{

            }
        },
        [格式化名称]:(value)=>{.....},
        //.....
    },
    en:{
        $types:{
            // [数据类型名称]:(value)=>{...},
        },
        [格式化名称]:(value)=>{.....},
        //.....更多的格式化器.....
    }
}

说明：

格式化器函数

每一个格式化器就是一个普通的同步函数，不支持异步函数。

典型的无参数的格式化器：(value)=>{....返回格式化的结果...}。

带参数的格式化器：(value,arg1,...)=>{....返回格式化的结果...}，其中value是上一个格式化器的输出结果。

类型格式化器

可以为每一种数据类型指定一个默认的格式化器，支持对String、Date、Error、Object、Array、Boolean、Number等数据类型的格式化。

当插值变量传入时，如果有定义了对应的的类型格式化器，会先调用该格式化器。

比如我们定义对Boolean类型格式化器，

//formatters.js

module.exports = {
    // 在所有语言下只作用于特定数据类型的格式化器   
    $types:{
        Boolean:(value)=> value ? "ON" : "OFF"
    }
} 
t("灯状态：{status}",true)  // === 灯状态：ON
t("灯状态：{status}",false)  // === 灯状态：OFF

在上例中，如果我们想在不同的语言环境下，翻译为不同的显示文本，则可以为不同的语言指定类型格式化器

//formatters.js
module.exports = {
    cn:{
        $types:{
            Boolean:(value)=> value ? "开" : "关"
        }
    },
    en:{
      $types:{
        Boolean:(value)=> value ? "ON" : "OFF" 
      }
    }
} 
// 当切换到中文时
t("灯状态：{status}",true)  // === 灯状态：开
t("灯状态：{status}",false)  // === 灯状态：关
// 当切换到英文时
t("灯状态：{status}",true)  // === 灯状态：ON
t("灯状态：{status}",false)  // === 灯状态：OFF

说明：

完整的类型格式化器定义形式
```
module.exports = {
    "*":{
        $types:{...}
    },    
    cn:{
        $types:{...}
    },
    en:{
      $types:{....}
    }
}
```
在匹配应用格式化时会先在当前语言的$types中查找匹配的格式化器，如果找不到再上*.$types中查找。
*.$types代表当所有语言中均没有定义时才匹配的类型格式化。
类型格式化器是默认执行的，不需要指定名称。
当前作用域的格式化器优先于全局的格式化器。（后续）

通用的格式化器

类型格式化器只针对特定数据类型，并且会默认调用。而通用的格式化器需要使用|管道符进行显式调用。

同样的，通用的格式化器定义在languages/formatters.js中。

module.exports = {
    "*":{
        $types:{...},
         [格式化名称]:(value)=>{.....},       
    },    
    cn:{
        $types:{...},
        [格式化名称]:(value)=>{.....},
    },
    en:{
      $types:{....},
      [格式化名称]:(value)=>{.....},
      [格式化名称]:(value,arg)=>{.....},        
    }
}

每一个格式化器均需要指定一个名称，在进行插值替换时会优先依据当前语言来匹配查找格式化器，如果找不到，再到键名为*中查找。

module.exports = {
    "*":{
        uppercase:(value)=>value
    },    
    cn:{
        uppercase:(value)=>["一","二","三","四","五","六","七","八","九","十"][value-1]
    },
    en:{
        uppercase:(value)=>["One","Two","Three","Four","Five","Six","seven","eight","nine","ten"][value-1]
    },
    jp:{
        
    }
}
// 当切换到中文时
t("{value | uppercase}",1)  // == 一
t("{value | uppercase}",2)  // == 二
t("{value | uppercase}",3)  // == 三
// 当切换到英文时
t("{value | uppercase}",1)  // == One
t("{value | uppercase}",2)  // == Two
t("{value | uppercase}",3)  // == Three
// 当切换到日文时，由于在该语言下没有定义uppercase格式式，因此到*中查找
t("{value | uppercase}",1)  // == 1
t("{value | uppercase}",2)  // == 2
t("{value | uppercase}",3)  // == 3

作用域格式化器

定义在languages/formatters.js里面的格式化器仅在当前工程生效，也就是仅在当前作用域生效。一般由应用开发者自行扩展。

关于作用域的概念详见后续介绍。

全局格式化器

定义在@voerkai18n/runtime里面的格式化器则全局有效，在所有场合均可以使用，但是其优先级低于作用域内的同名格式化器。目前内置的格式化器有：

名称		说明

扩展格式化器

除了可以在当前项目languages/formatters.js自定义格式化器和@voerkai18n/runtime里面的全局格式化器外，单列了@voerkai18n/formatters项目用来包含了更多的格式化器。

作为开源项目，欢迎大家提交贡献更多的格式化器。

日期时间

@voerkai18n/runtime内置了对日期时间进行处理的格式化器，可以直接使用，不需要额外的安装。

// 切换到中文
t("现在是{d | date}",new Date())       // ==  现在是2022年3月12日
t("现在是{d | time}",new Date())       // ==  现在是18点28分12秒
t("现在是{d | shorttime}",new Date())  // ==  现在是18:28:12
t("现在是{}",new Date())               // ==  现在是2022年3月12日 18点28分12秒

// 切换到英文
t("现在是{d | date}",new Date())   // ==  Now is 2022/3/12
t("现在是{d | time}",new Date())   // ==  Now is 18:28:12
t("现在是{}",new Date())           // ==  Now is 2022/3/20 19:17:24'

复数

当翻译文本内容是一个数组时启用复数处理机制。即在langauges/tranclates/*.json中的文本翻译项是一个数据。

启用复数处理机制

假设在index.html文件中具有一个翻译内容

    t("我{}一辆车")

经过extract命令提取为翻译文件后，如下：

// languages/translates/default.json
{
    "我有{}辆车":{
        "en":"",
        "de":"...." 
    }
}

现在我们要求引入复数处理机制，为不同数量采用不同的翻译，只需要将上述翻译文本更改为数组形式。

{
    "我有{}辆车":{
        "en":["I don't have car","I have a car","I have two cars","I have {} cars"],
        "en":["I don't have car","I have a car","I have {} cars"],
        "en":["I don't have car","I have {} cars"],
        "de":"...." 
    }
}

上例中，只需要在翻译文件中将上述的en:""更改为[<0对应的复数文本>,<1对应的复数文本>,...,<n对应的复数文本>]形式代表启动复数机制.

可以灵活地为每一个数字(0、1、2、...、n)对应的复数形式进行翻译
数量数字大于数组长度，则总是取最后一个复数形式
复数形式的文本同样支持位置插值和变量插值。

对应的翻译函数

启用复数处理机制后，在t函数根据变量值来决定采用单数还是复数，按如下规则进行处理。

不存在插值变量且t函数的第2个参数是数字


t("我有一辆车",0)  // ==   "I don't have a car"
t("我有一辆车",1)  // ==   "I have a car"
t("我有一辆车",2)  // ==   "I have two cars"
t("我有一辆车",100)  // == "I have 100 cars"

存在插值变量且t函数的第2个参数是数字

就中文而言，上述没有指定插值变量是比较别扭的，一般可以引入一个位置插值变量更加友好。


t("我有{}辆车",0)          // ==   "I don't have a car"
t("我有{}辆车",1)          // ==   "I have a car"
t("我有{}辆车",2)          // ==   "I have two cars"
t("我有{}辆车",100)      // == "I have 100 cars"

复数命名插值变量

当启用复数功能时，t函数需要知道根据哪个变量来决定采用何种复数形式。

当采用位置变量插值时，t函数取第一个数字类型参数作为位置插值复数。

t("{}有{}辆车","张三",0)

当采用命名变量插值时，t函数约定当插值字典中存在以$字符开头的变量时，并且值是数字时，根据该变量来引用复数。

下例中，t函数根据$count值来处理复数。

t("{name}有{$count}辆车",{name:"张三",$count:1})

示例

// languages/translates/default.json
{
    "第{}章":{
        en:[
            "Chapter Zero","Chapter One", "Chapter Two", "Chapter Three","Chapter Four",
            "Chapter Five","Chapter Six","Chapter Seven","Chapter Eight","Chapter Nine",
            "Chapter {}"
        ],
        cn:["起始","第一章", "第二章", "第三章","第四章","第五章","第六章","第七章","第八章","第九章",“第{}章”]
    }
}
// 翻译函数
t("第{}章",0)  // == Chapter Zero
t("第{}章",1)  // == Chapter One
t("第{}章",2)  // == Chapter Two
t("第{}章",3)  // == Chapter Three
t("第{}章",4)  // == Chapter Four
t("第{}章",5)  // == Chapter Five
t("第{}章",6)  // == Chapter Six
t("第{}章",7)  // == Chapter Seven
...
// 超过取最后一项
t("第{}章",100)  // == Chapter 100

字典

voerkiai18n内置一个dict格式化器，可以直接使用。

// 假设网络状态取值：0=初始化,1=正在连接，2=已连接,3=正在断开.4=已断开,>4=未知

t("当前状态:{status | dict(0,'初始化',1,'正在连接'，2,'已连接',3,'正在断开',4,'已断开','未知') }",status)

货币

名称空间

voerkai18n 的名称空间是为了解决当源码文件非常多时，通过名称空间对翻译内容进行分类翻译的。

假设一个大型项目，其中源代码文件有上千个。默认情况下，voerkai18n extract会扫描所有源码文件将需要翻译的文本提取到languages/translates/default.json文件中。由于文件太多会导致以下问题：

内容太多导致default.json文件太大，有利于管理
有些翻译往往需要联系上下文才可以作出更准确的翻译，没有适当分类，不容易联系上下文。

因此，引入名称空间就是目的就是为了解决此问题。

配置名称空间，需要配置languages/settings.json文件。

// 工程目录：d:/code/myapp
// languages/settings.json
module.exports = {
    namespaces:{
        //"名称":"相对路径"，
        “routes”:“routes”,
        "auth":"core/auth",
        "admin":"views/admin"
    }
}

以上例子代表：

将d:\code\myapp\routes中扫描到的文本提取到routes.json中。
将d:\code\myapp\auth中扫描到的文本提取到auth.json中。
将d:\code\myapp\views/admin中扫描到的文本提取到admin.json中。

最终在 languages/translates中会包括：

languages
  |-- translates
      |-- default.json
      |-- routes.sjon
      |-- auth.json
      |-- admin.json

然后，voerkai18n compile在编译时会自动合并这些文件，后续就不再需要名称空间的概念了。

名称空间仅仅是为了解决当翻译内容太多时的分类问题。

多库联动

voerkai18n 支持多个库国际化的联动和协作，即当主程序切换语言时，所有引用依赖库也会跟随主程序进行语言切换，整个切换过程对所有库开发都是透明的。

结构图

当我们在开发一个应用或者库并import "./languages"时，在langauges/index.js进行了如下处理：

创建一个i18nScope作用域实例
检测当前应用环境下是否具有全局单例VoerkaI18n
- 如果存在VoerkaI18n全局单例，则会将当前i18nScope实例注册到VoerkaI18n.scopes中
- 如果不存在VoerkaI18n全局单例，则使用当前i18nScope实例的参数来创建一个VoerkaI18n全局单例。
在每个应用与库中均可以使用import { t } from ".langauges导入本工程的t翻译函数，该t翻译函数被绑定当前i18nScope作用域实例，因此翻译时就只会使用到本工程的文本。这样就割离了不同工程和库之间的翻译。
由于所有引用的i18nScope均注册到了全局单例VoerkaI18n，当切换语言时，VoerkaI18n会刷新切换所有注册的i18nScope，这样就实现了各个i18nScope即独立，又可以联动语言切换。

自动导入翻译函数

使用voerkai18 compile后，要进行翻译时需要从./languages导入t翻译函数。

import { t } from "./languages"

由于默认情况下，voerkai18 compile命令会在当前工程的/languages文件夹下，这样我们为了导入t翻译函数不得不使用各种相对引用，这即容易出错，又不美观，如下：

import { t } from "./languages"
import { t } from "../languages"
import { t } from "../../languages"
import { t } from "../../../languages"

作为国际化解决方案，一般工程的大部份源码中均会使用到翻译函数，这种使用体验比较差。

为此，我们提供了一个babel插件来自动完成翻译函数的自动引入。使用方法如下：

在babel.config.js中配置插件

const i18nPlugin =  require("@voerkai18n/babel")
module.expors = {
    plugins: [
        [
            i18nPlugin,
            {
                // 可选，指定语言文件存放的目录，即保存编译后的语言文件的文件夹
                // 可以指定相对路径，也可以指定绝对路径
                // location:"",

                autoImport:"#/languages"  
            }            
        ]
    ]
}

这样，当在进行babel转码时，就会自动在js源码文件中导入t翻译函数。

babel-plugin-voerkai18n插件支持以下参数:

location
配置langauges文件夹位置，默认会使用当前文件夹下的languages文件。
因此，如果你的babel.config.js在项目根文件夹，而languages文件夹位于src/languages，则可以将location="src/languages"，这样插件会自动从该文件夹读取需要的数据。
autoImport
用来配置导入的路径。比如 autoImport="#/languages" ，则当在babel转码时，如果插件检测到t函数的存在并没有导入，就会自动在该源码中自动导入import { t } from "#/languages"
配置autoImport时需要注意的是，为了提供一致的导入路径，视所使用的打包工具或转码插件，如webpack、rollup等。比如使用babel-plugin-module-resolver
```
module.expors = {
    plugins: [
        [
            "module-resolver",
            {
                root:"./",
                alias:{
                    "languages":"./src/languages"
                }
            }            
        ]
    ]
}
```
这样配置autoImport="languages"，则自动导入import { t } from "languages"。
如webpack、rollup等打包工具也有类似的插件可以实现别名等转换，其目的就是让babel-plugin-voerkai18n插件能自动导入固定路径，而不是各种复杂的相对路径。

文本映射

虽然VoerkaI18n推荐采用t("中华人民共和国万岁")形式的符合直觉的翻译形式，而不是采用t("xxxx.xxx")这样不符合直觉的形式，但是为什么大部份的国际化方案均采用t("xxxx.xxx")形式？

在我们的方案中，t("中华人民共和国万岁")形式相当于采用原始文本进行查表，语言名形式如下：

// en.js
{
    "中华人民共和国":"the people's Republic of China"
}
// jp.js
{
    "中华人民共和国":"中華人民共和国"
}

很显然，直接使用文本内容作为key，虽然符合直觉，但是会造成大量的冗余信息。因此，voerkai18n compile会将之编译成如下：

//idMap.js
{
    "1":"中华人民共和国万岁"
}
// en.js
{
    "1":"Long live the people's Republic of China"
}
// jp.js
{
    "2":"中華人民共和国"
}

如此，就消除了在en.js、jp.js文件中的冗余。但是在源代码文件中还存在t("中华人民共和国万岁")，整个运行环境中存在两份副本，一份在源代码文件中，一份在idMap.js中。

为了进一步减少重复内容，因此，我们需要将源代码文件中的t("中华人民共和国万岁")更改为t("1")，这样就能确保无重复冗余。但是，很显然，我们不可能手动来更改源代码文件，这就需要由babel插件来做这一件事了。

babel-plugin-voerkai18n插件同时还完成一份任务，就是自动读取voerkai18n compile生成的idMap.js文件，然后将t("中华人民共和国万岁")自动更改为t("1")，这样就完全消除了重复冗余信息。

所以，在最终形成的代码中，实际上每一个t函数均是t("1")、t("2")、t("3")、...、t("n")的形式，最终代码还是采用了用key来进行转换，只不过这个过程是自动完成的而已。

注意：如果没有启用babel-plugin-voerkai18n插件，还是可以正常工作，但是会有一份默认语言的冗余信息存在。

切换语言

可以通过全局单例或当前作用域实例切换语言。

import { i18nScope } from "./languages"

// 切换到英文
await i18nScope.change("en")
// VoerkaI18n是一个全局单例，可以直接访问
VoerkaI18n.change("en")

侦听语言切换事件：

import { i18nScope } from "./languages"

// 切换到英文
i18nScope.on((newLanguage)=>{
    ...
})
// 
VoerkaI18n.on((newLanguage)=>{
    ...
})

加载语言包

当使用webpack、rollup进行项目打包时，默认语言包采用静态打包，会被打包进行源码中。而其他语言则采用异步打包方式。在languages/index.js中

const defaultMessages =  require("./cn.js")  
const activeMessages = defaultMessages
  
// 语言作用域
const scope = new i18nScope({
    default:   defaultMessages,                 // 默认语言包
    messages : activeMessages,                  // 当前语言包
    ....
    loaders:{ 
        "en" : ()=>import("./en.js") 
        "de" : ()=>import("./de.js") 
        "jp" : ()=>import("./jp.js") 
    })

babel插件

全局安装@voerkai18n/babel插件用来进行自动导入t函数和自动文本映射。

> npm install -g @voerkai18n/babel
> yarn global add @voerkai18n/babel
> pnpm add -g @voerkai18n/babel

然后在babel.config.js中使用，详见上节自动导入翻译函数介绍。

Vue扩展

React扩展

命令行

全局安装@voerkai18n/cli工具。

> npm install -g @voerkai18n/cli
> yarn global add @voerkai18n/cli
> pnpm add -g @voerkai18n/cli

然后就可以执行：

> voerkai18n init
> voerkai18n extract
> voerkai18n compile

如果没有全局安装，则需要：

> yarn voerkai18n init
> yarn voerkai18n extract
> yarn voerkai18n compile
---
> pnpm voerkai18n init
> pnpm voerkai18n extract
> pnpm voerkai18n compile

init

用于在指定项目创建voerkai18n国际化配置文件。

> voerkai18n init --help
初始化项目国际化配置
Arguments:
  location                           工程项目所在目录
Options:
  -D, --debug                        输出调试信息
  -r, --reset                        重新生成当前项目的语言配置
  -lngs, --languages <languages...>  支持的语言列表 (default: ["cn","en"])
  -d, --defaultLanguage              默认语言
  -a, --activeLanguage               激活语言
  -h, --help                         display help for command

使用方法如下：

首先需要在工程文件下运行voerkai18n init命令对当前工程进行初始化。

//- `lngs`参数用来指定拟支持的语言名称列表
> voerkai18n init . -lngs cn en jp de -d cn

运行voerkai18n init命令后，会在当前工程中创建相应配置文件。

myapp
  |-- languages 
    |-- settings.json               // 语言配置文件
  |-- package.json
  |-- index.js

settings.json文件很简单，主要是用来配置要支持的语言等基本信息。

module.exports = {
    // 拟支持的语言列表
    "languages": [
        {
            "name": "cn",
            "title": "中文"
        },
        {
            "name": "en",
            "title": "英文"
        }
    ],
    // 默认语言，即准备在源码中写的语言，一般我们可以直接使用中文
    "defaultLanguage": "cn",
    // 激活语言，即默认要启用的语言，一般等于defaultLanguage
    "activeLanguage": "cn",
    // 翻译名称空间定义，详见后续介绍。
    "namespaces": {}
}

说明：

您也可以手动自行创建languages/settings.json文件。这样就不需运行voerkai18n init命令了。
如果你的源码放在src文件夹，则init命令会自动在在src文件夹下创建languages文件夹。
voerkai18n init是可选的，直接使用extract时也会自动创建相应的文件。
-m参数用来指定生成的settings.json的模块类型：
- 当-m=auto时，会自动读取前工程package.json中的type字段
- 当-m=esm时，会生成ESM模块类型的settings.json。
- 当-m=cjs时，会生成commonjs模块类型的settings.json。
location参数是可选的，如果没有指定则采用当前目录。
如果你想将languages安装在src/languages下，则可以指定voerkai18n init ./src

extract

扫描提取当前项目中的所有源码，提取出所有需要翻译的文本内容并保存在到<工程源码目录>/languages/translates/*.json。

> 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,html
extract是基于正则表达式方式进行匹配的，而不是像i18n-next采用基于AST解析。

重点：
默认情况下，voerkai18n extract可以安全地反复多次执行，不会导致已经翻译一半的内容丢失。
如果想添加新的语言支持，也voerkai18n extract也可以如预期的正常工作。

compile

编译当前工程的语言包，编译结果输出在./langauges文件夹。

Usage: voerkai18n compile [options] [location]

编译指定项目的语言包

Arguments:
  location                  工程项目所在目录 (default: "./")

Options:
  -D, --debug               输出调试信息
  -m, --moduleType [types]  输出模块类型,取值auto,esm,cjs (default: "esm")
  -h, --help                display help for command

voerkai18n compile执行后会在langauges文件夹下输出：

myapp
  |--- langauges
    |-- index.js              // 当前作用域的源码
    |-- idMap.js              // 翻译文本与id的映射文件
    |-- formatters.js         // 自定义格式化器
    |-- cn.js                 // 中文语言包
    |-- en.js                 // 英文语言包 
    |-- xx.js                 // 其他语言包
    |-- ...

说明：

在当前工程目录下，一般不需要指定参数就可以反复多次进行编译。
您每次修改了源码并extract后，均应该再次运行compile命令。
如果您修改了formatters.js，执行compile命令不会修改该文件。

API

i18nScope

每个工程会创建一个i18nScope实例。

import { i18nScope } from "./languages"

// 订阅语言切换事件
i18nScope.on((newLanguage)=>{...})
// 取消语言切换事件订阅
i18nScope.off(callback)
// 当前作用域配置
i18nScope.settings
// 当前语言
i18nScope.activeLanguage         // 如cn

// 默认语言
i18nScope.defaultLanguage         
// 返回当前支持的语言列表，可以用来显示
i18nScope.languages    // [{name:"cn",title:"中文"},{name:"en",title:"英文"},...]
// 返回当前作用域的格式化器                         
i18nScope.formatters   
// 当前作用id
i18nScope.id
// 切换语言，异步函数
await i18nScope.change(newLanguage)
// 当前语言包                         
i18nScope.messages        // {1:"...",2:"...","3":"..."}
// 引用全局VoerkaI18n实例                         
i18nScope.global
// 注册当前作用域格式化器
i18nScope.registerFormatter(name,formatter,{language:"*"})

VoerkaI18n

当import {} form "./languages"时会自动创建全局单VoerkaI18n

// 订阅语言切换事件
VoerkaI18n.on((newLanguage)=>{...})
// 取消语言切换事件订阅
VoerkaI18n.off(callback)
// 取消所有语言切换事件订阅
VoerkaI18n.offAll()
                              
// 返回当前默认语言
VoerkaI18n.defaultLanguage
// 返回当前激活语言
VoerkaI18n.activeLanguage
// 返回当前支持的语言
VoerkaI18n.languages                              
// 切换语言
await VoerkaI18n.change(newLanguage)
// 返回全局格式化器
VoerkaI18n.formatters                              
// 注册全局格式化器
VoerkaI18n.registerFormatter(name,formatter,{language:"*"})

开源项目：https://gitee.com/zhangfisher...

新鲜出炉的Nodejs/Vue/React多语言解决方案

前言

安装

快速入门

第一步：初始化工程

第二步：提取文本

第三步：翻译文本

第四步：编译语言包

第五步：导入翻译函数

第六步：切换语言

指南

翻译函数

插值变量

命名插值变量

位置插值变量

插值变量格式化

格式化器语法

自定义格式化器

格式化器函数

类型格式化器

通用的格式化器

作用域格式化器

全局格式化器

扩展格式化器

日期时间

复数

启用复数处理机制

对应的翻译函数

字典

货币

名称空间

多库联动

自动导入翻译函数

文本映射

切换语言

加载语言包

babel插件

Vue扩展

React扩展

命令行

init

extract

compile

API

i18nScope

VoerkaI18n

zhangfisher

引用和评论

最佳实践：如何实现函数参数之间的TS类型相依赖和自动推断

腾讯新闻中心首页改版啦

前端如何入门 Go 语言

100个React最佳实践小技巧

前端开发工具

开发插件集合

JS校验身份证号