VitePress

简体中文

English

简体中文

English

Appearance

快速入门 ​

VoerkaI18n是一个通用的面向Javascript/Typescript的国际化解决方案，支持Vue、React、Svelte、Nextjs等主流框架。

本节以标准的Nodejs js应用程序为例，简要介绍VoerkaI18n国际化框架的基本使用流程。

  • myapp
    • package.json
    • src
    • index.js

上述树组件基于Lite-Tree构建。

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

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

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

第一步：安装命令行工具 ​

安装@voerkai18n/cli到全局，提供voerkai18n命令。

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

第二步：初始化工程 ​

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

javascript
> voerkai18n init

voerkai18n init命令会提供一个交互式的命令行界面，用来初始化多语言环境。

当初始化完成后，会创建创建一个语言工作目录，默认位置是src/languages。

该语言目录结构大致如下：

  • myapp
    • src
      • languages
        • api.json
        • component.js 翻译组件
        • index.js 入口文件
        • messages
        • paragraphs
        • prompts
        • settings.json
        • storage.js
        • loader.js
        • transform.js
        • formatters.json 格式化器配置
        • translates提取需要翻译的内容
    • package.json
    • index.js

提示

更多的voerkai18n init命令的使用请查阅这里

第三步：标识翻译内容 ​

接下来在源码文件中，将所有需要翻译的内容使用t翻译函数进行包装，如下：

javascript
import { t } from "./languages"
// 不含插值变量
t("中华人民共和国")
// 位置插值变量
t("中华人民共和国{}","万岁")
t("中华人民共和国成立于{}年，首都{}",[1949,"北京"])
  • t翻译函数只是一个普通函数，您需要为之提供执行环境，关于t翻译函数的更多用法见这里

第四步：提取文本 ​

接下来我们使用voerkai18n extract命令来自动扫描工程源码文件中的需要的翻译的文本信息。 voerkai18n extract命令会使用正则表达式来提取t("提取文本")包装的文本。

shell
myapp>voerkai18n extract

voerkai18n extract命令的作用就是提取所有需要翻译的内容，保存到myapp/languages/translates/messages/default.json。

  • translates/messages/default.json ： 该文件就是从当前工程扫描提取出来的需要进行翻译的文本信息。所有需要翻译的文本内容均会收集到该文件中。

最后文件结构如下：

  • myapp
    • src
      • languages
        • api.json
        • component.js 翻译组件
        • index.js 入口文件
        • messages
        • paragraphs
        • prompts
        • settings.json
        • storage.js
        • loader.js
        • translates/提取需要翻译的内容
          • messages
            • default.json 需要翻译的内容提取到这里
    • package.json
    • index.js

第五步：人工翻译 ​

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

json
{
    "欢迎使用VoerkaI18n":{
        "en":"<在此编写对应的英文翻译内容>",
        "de":"<在此编写对应的德文翻译内容>",
        "jp":"<在此编写对应的日文翻译内容>",
        "$files":["index.js"],    // 记录了该信息是从哪几个文件中提取的
        "$id":1
    },
	"VoerkaI18n是一款非常棒的国际化解决方案":{
        "en":"<在此编写对应的英文翻译内容>",
        "de":"<在此编写对应的德文翻译内容>",
        "jp":"<在此编写对应的日文翻译内容>",
        "$files":["index.js"],
        "$id":2
    }
}

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

提示

如果翻译期间对源文件进行了修改，则只需要重新执行一下voerkai18n extract命令,VoerkaI18n会自动合并新的翻译内容到translates/messages文件夹下的JSON文件中。 反复执行voerkai18n extract命令是安全的，不会导致进行了一半的翻译内容丢失，可以放心执行。

第六步：自动翻译 ​

voerkai18n支持通过voerkai18n translate命令来实现调用在线翻译服务进行自动翻译。

从voerkai18n 3.0开发除了百度翻译，优先支持采用AI翻译

javascript
// 使用百度翻译
>voerkai18n translate --api-key <在百度翻译上申请的密钥> --api-id <在百度翻译上申请的appid> --provider baidu
// 使用AI翻译，支持OpenAI兼容的大模型PI
>voerkai18n translate --api-key <API密钥> --api-url <AI API URL> --api-model <模型名称>

在项目文件夹下执行上面的语句，将会自动调用在线翻译API进行翻译，以现在的翻译水平而言，您只需要进行少量的微调即可。关于voerkai18n translate命令的使用请查阅后续介绍。

第七步：编译语言包 ​

当我们完成myapp/languages/translates/messages下的所有JSON语言文件的翻译后，接下来需要对翻译后的文件进行编译。

shell
myapp> voerkai18n compile

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

  • myapp
    • languages
      • settings.json 语言配置文件
      • index.js 包含该应用作用域下的翻译函数等
      • storage.js
      • loader.js
      • formatters.json 格式化器配置
      • component.js 翻译组件
      • api.json 翻译API配置
      • +messages 编译生成的语言包
        • +idMap.js 文本信息id映射表
        • +zh.js 语言包
        • +en.js 语言包
        • +jp.js
        • +de.js
      • translates 此文件夹包含了所有需要翻译的内容
        • messages
          • default.json
    • package.json
    • index.js

第八步：导入翻译函数 ​

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

javascript
import { t } from "./languages"

因此，我们需要在需要进行翻译时导入该函数即可。

但是如果源码文件很多，重次重复导入t函数也是比较麻烦的，推荐采用unplugin-auto-import插件来自动导入t函数。

第九步：切换语言 ​

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

javascript
import { i18nScope } from "./languages"

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

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

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

javascript
import { i18nScope } from "./languages"

// 切换到英文
i18nScope.on("change",(newLanguage)=>{
    // 在此重新渲染界面
    ...

})
// 
VoerkaI18n.on("change",(newLanguage)=>{
     // 在此重新渲染界面
     ...
})

针对不同的前端框架，提供了相应开箱即用的库来简化，包括vue/vue2/svelte/nextjs/...等。

第十步：语言包补丁 ​

一般情况下，多语言的工程化过程就结束了，voerkai18n在多语言实践考虑得更加人性化。有没有经常发现这样的情况，当项目上线后，才发现：

  • 翻译有误
  • 客户对某些用语有个人喜好，要求你更改。
  • 临时要增加支持一种语言

一般碰到这种情况，只好重新打包构建工程，重新发布，整个过程繁琐而麻烦。 现在voerkai18n针对此问题提供了完美的解决方案，可以通过服务器来为应用打语言包补丁和动态增加语言支持，而不需要重新打包应用和修改应用。

方法如下：

  1. 打开languages/loader.{js|ts}修改语言包加载器函数，用来从服务器加载语言包文件。
javascript

module.exports = async (language,scope)=>{
    return await (await fetch(`/languages/${scope.id}/${language}.json`)).json()
}
  1. 将语言包补丁文件保存在Web服务器上指定的位置/languages/<应用名称>/<语言名称>.json即可。
  2. 当应用启动后会自动从服务器上加载语言补丁包合并，从而实现动为语言包打补丁的功能。
  3. 利用该特性也可以实现动态增加临时支持一种语言的功能

更完整的说明详见动态加载语言包和语言包补丁功能介绍。

提示

利用此特性，可以实现动态增加语言支持，动态打补丁等功能。

小结 ​

  • 在源代码中使用t函数包装要翻译的文本信息。如果是React/Vue等框架，可以使用VoerkaI18n提供的<Translate>组件。
  • 基本工作流：
    • 使用voerkai18n extract命令提取要翻译的文本信息，可以重复执行自动同步。
    • 使用voerkai18n translate命令调用在线翻译服务进行自动翻译。
    • 使用voerkai18n compile命令编译语言包。