update docs
This commit is contained in:
wxzhang
parent
be987ebd6e
commit
154e015fa5
@ -40,6 +40,7 @@ export default defineConfig({
|
||||
"/guide/intro/install.md",
|
||||
"/guide/intro/get-started.md",
|
||||
"/guide/intro/versions.md",
|
||||
"/guide/intro/history.md",
|
||||
"/guide/intro/support.md",
|
||||
"/guide/intro/question.md"
|
||||
],
|
||||
|
||||
@ -17,9 +17,9 @@ import { t } from "../../../languages"
|
||||
|
||||
作为国际化解决方案，一般工程的大部份源码中均会使用到翻译函数，这种使用体验比较差。
|
||||
|
||||
为此，我们提供了一个几个插件可以来自动完成翻译函数的自动引入，包括：
|
||||
为此，我们提供了几个插件可以来自动完成翻译函数的自动导入，包括：
|
||||
|
||||
- `babel`插件
|
||||
- `vite`插件
|
||||
|
||||
关于插件如何使用请参阅文档。
|
||||
当启用了`babel/vite`插件后，就会在编译时自动导入`t`函数。关于插件如何使用请参阅文档。
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
|
||||
- 内置的`voerkai18n translate`命令能调用在线翻译服务完成对提取的文本的自动翻译。
|
||||
|
||||
- 目前支持访问百度在线API进行自动翻译。百度提供了免费的在线API，虽然只支持`QPS=1`，即每秒调用一次。但是`voerkai18n translate`命令会对要翻译的文本进行合并后再调用，因此大部分情况下，均足够使用了。
|
||||
- 目前支持访问`百度在线API`进行自动翻译。百度提供了免费的在线API，虽然只支持`QPS=1`，即每秒调用一次。但是`voerkai18n translate`命令会对要翻译的文本进行合并后再调用，因此大部分情况下，均足够使用了。
|
||||
|
||||
|
||||
`voerkai18n translate`命令的使用请参阅扩展文档。
|
||||
`voerkai18n translate`命令的使用请参见[命令行工具](../tools/cli)
|
||||
|
||||
@ -1,10 +1,10 @@
|
||||
# 框架集成
|
||||
|
||||
`voerkai18n`可用应用于绝大多数框架，包括但不限于`Vue`、`React`、`Angular`、`Svelte`等等。要为某个框架或库集成VoerkaI18n的功能，一般需要完成以下几件事：
|
||||
`voerkai18n`可用应用于绝大多数框架，包括但不限于`Vue`、`React`、`Angular`、`Svelte`等等。要为某个框架或库集成`VoerkaI18n`的功能非常简单，一般需要完成以下几件事：
|
||||
|
||||
## 执行`t`翻译函数
|
||||
|
||||
翻译本质上是非常简单的查表功能，原则上只需要将所有需要翻译的字符串使用`t`函数包装起来即可。因此，只需要具备执行`t`函数的条件即可。而这是比较容易做到的，没有任何难度。
|
||||
翻译本质上是非常简单的查表功能，原则上只需要将所有需要翻译的字符串使用`t`函数包装起来即可。因此，只需要为`t`函数提供执行条件即可。而这是比较容易做到的，没有任何难度。
|
||||
|
||||
一般只需要`import { t } from "./languages"`即可直接使用`t`函数，不需要任何配置。`./languages`里面的文件本身就是您项目源码的一部分。
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
|
||||
## 自动导入`t`翻译函数
|
||||
|
||||
由于需要在所以需要使用`t`翻译函数的文件均需要导入，比较麻烦。为了简化导入工作，`voerkai18n`提供了`babel`、`vite`、`webpack`插件，配置好以后，可以扫描发现在源码中使用了`t`函数，就自动进行导入。这几个插件基本上涵盖了大部份Javascrip工程场景，应用这些插件后，`t`函数就相当于是一个全局函数，可以在项目中直接使用而不必进行导入。
|
||||
由于需要在所有需要使用`t`翻译函数的文件均需要导入，比较麻烦。为了简化导入工作，`voerkai18n`提供了`babel`、`vite`、`webpack`插件，配置好以后，可以自动扫描源码，如果发现在源码中使用了`t`函数，就自动进行导入。这几个插件基本上涵盖了大部份`Javascrip`工程场景，应用这些插件后，`t`函数就相当于是一个全局函数，可以在项目中直接使用而不必进行导入。
|
||||
|
||||
自动导入`t`翻译函数仅是改善编程体验，并不是必须的。
|
||||
|
||||
@ -25,7 +25,7 @@
|
||||
```javascript | pure
|
||||
import { i18nScope } from "./languages"
|
||||
await i18nScope.change("<新语言>")
|
||||
// 或者调用全局
|
||||
// 或者调用全局实例
|
||||
VoerkaI18n.change("<新语言>")
|
||||
```
|
||||
|
||||
@ -46,13 +46,13 @@
|
||||
import { i18nScope } from "./languages"
|
||||
i18nScope.on((newLanguage)=>{
|
||||
app._instance.update() // 强制重新渲染
|
||||
activeLanguage.value = newLanguage
|
||||
//......
|
||||
})
|
||||
```
|
||||
|
||||
## 小结
|
||||
|
||||
了解了上述基本原理，为`Vue`、`React`、`Angular`、`Svelte`、`uniapp`、`ReactNative`等应用程序集成`voerkai18n`就非常容易。
|
||||
了解了上述基本原理，为`Vue`、`React`、`Angular`、`Svelte`、`Solid`、`uniapp`、`ReactNative`等应用程序集成`voerkaI18n`就非常容易。
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,16 +1,17 @@
|
||||
# 在线编辑语言包
|
||||
# 在线编辑应用界面
|
||||
|
||||
利用**动态加载语言包**的机制，开发者可以非常容易就开发出`让用户自行编辑界面语言`的功能。
|
||||
|
||||
请详细阅读[`远程加载语言包`](./remote-load)的实现过程，其基本思路如下：
|
||||
一般前端应用，UI界面的各种显示内容在开发构建部署后就相对固定了。`VoerkaI18n`不仅让开发者可以很容易地利用语言包补丁机制实现在应用发布后的界面更新修复。更进一步地，利用`VoerkaI18n`**动态加载语言包**的机制，还可以让您很容易地扩展充满想象力的功能：**让用户自行随时编辑修改界面语言**。
|
||||
|
||||
**其基本思路如下：**
|
||||
- 后端采用数据库来保存语言包，每一个语言包可以用一个表或多个表存储。
|
||||
- 编写对应的编辑语言包的Web API,实现通过API修改语言包功能
|
||||
- 前端代码重写语言包加载器函数，将原来的读取静态语言包的方式，修改为采用API读取
|
||||
- 前端增加编辑语言包的界面
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
此功能的实现涉及到后端实现，`VoerkaI18n`未提供开箱即用的功能，让开发者自行扩展。
|
||||
|
||||
请详细阅读[`远程加载语言包`](./remote-load)的实现过程。
|
||||
|
||||
|
||||
|
||||
@ -16,7 +16,8 @@ const scope = new i18nScope({
|
||||
"en" : ()=>import("./en.js")
|
||||
"de" : ()=>import("./de.js")
|
||||
"jp" : ()=>import("./jp.js")
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
利用异步打包机制，从而避免将多个语言静态打包到源码包。
|
||||
@ -43,11 +43,11 @@ const scope = new i18nScope({
|
||||
})
|
||||
/// ....
|
||||
```
|
||||
- 可以看到在`languages/index.js`中创建了一个以当前工程`package.json`的`name`为`id`的`i18nScope`实例，然后注册到全局`voerkaI18n`实例中。
|
||||
- 可以看到在`languages/index.js`中创建了一个以当前工程`package.json`的`name`为`id`的`i18nScope`实例，其会自动注册到全局`voerkaI18n`实例中。
|
||||
- 为`en`语言创建了一个异步加载器，用来异步加载`en`语言包。
|
||||
- 当打包`chat`应用时，`cn.js`、`en.js`等语言包均作为源码的一部分打包，差别在于非默认语言`en.js`单独作为一个`chunk`打包以便能异步加载。
|
||||
- 当打包`chat`应用时，`zh.js`、`en.js`等语言包均作为源码的一部分打包，差别在于非默认语言`en.js`单独作为一个`chunk`打包以便能异步加载。
|
||||
|
||||
下面假设，当应用上线后，客户要求增加`de`语言，但是我们的源码包中并没有包含`de`语言，利用`voerkiai18n`语言加载器功能，可以比较方便地实现动态增加支持语言的功能。
|
||||
**下面假设**，当应用上线后，客户要求增加`de`语言，但是我们的源码包中并没有包含`de`语言，利用`voerkiai18n`语言加载器功能，可以比较方便地实现`动态增加语种`的功能。
|
||||
|
||||
### 第一步：注册默认的语言加载器
|
||||
|
||||
@ -55,7 +55,7 @@ const scope = new i18nScope({
|
||||
当注册了一个默认的语言包加载器后,如果切换到一个未注册的语言时，会调用默认的语言包加载器来获取语言包。
|
||||
利用此特性就可以实现随时动态为应用增加语言支持的特性。
|
||||
|
||||
首先需要在应用中导入`i18nScope`实例，然后注册一个默认的语言加载器。
|
||||
首先需要在应用中(例如`app.js`或`main.js`等)导入`i18nScope`实例，然后注册一个默认的语言加载器。
|
||||
|
||||
```javascript | pure
|
||||
|
||||
@ -100,12 +100,12 @@ i18nScope.registerDefaultLoader(async (language,scope)=>{
|
||||
**例如**：
|
||||
- 应用`A`，依赖于包/库`X`、`Y`、`Z`，并且`A/X/Y/Z`均使用了`voerkiai18n`作为多语言解决方案
|
||||
- 当应用启动时，`A/X/Y/Z`均会创建一个`i18nScope`实例，其`id`分别是`A/X/Y/Z`，然后这些`i18nScope`实例会注册到全局的`voerkaI18n`实例中（详见多库联动介绍）。
|
||||
- 假如应用`A`配置支持`zh`、`cn`两种语言,当应用要切换到`de`语言时，那么不仅是`A`应用本身需要切换到`de`语言,所依赖的库也需要切换到`de`语言。但是库`X`、`Y`、`Z`本身可能支持`de`语言，也可以不支持。如果不支持，则同样需要向服务器请求该库的翻译语言。因此，在向服务器请求时就需要带上`scope.id`。
|
||||
- 假如应用`A`配置支持`zh`、`en`两种语言,当应用要切换到`de`语言时，那么不仅是`A`应用本身需要切换到`de`语言,所依赖的库也需要切换到`de`语言。但是库`X`、`Y`、`Z`本身可能支持`de`语言，也可能不支持。如果不支持，则同样需要向服务器请求该库的翻译语言。因此，在向服务器请求时就需要带上`scope.id`,这样服务器就可以分别为应用`A`和依赖库`X`、`Y`、`Z`均准备对应的语言包了。
|
||||
|
||||
|
||||
### 第三步：将语言包文件保存在服务器
|
||||
|
||||
在上一步中，我们通过`fetch(/languages/${scope.id}/${language}.json)`来传递读取语言包（您可以使用任意您喜欢的方式），这意味着我们需要在web服务器上根据此URL来组织语言包，以便可以下载到语言包。比如可以使用如下：
|
||||
在上一步中，我们通过`fetch(/languages/${scope.id}/${language}.json)`来传递读取语言包（您可以使用任意您喜欢的方式,如`axios`），这意味着我们需要在web服务器上根据此`URL`来组织语言包，以便可以下载到语言包。比如可以这样组织：
|
||||
```javascript | pure
|
||||
webroot
|
||||
|-- languages
|
||||
@ -119,7 +119,7 @@ webroot
|
||||
|-- de.json
|
||||
```
|
||||
|
||||
`voerkaI18n`将编写**如何语言加载器**和**如何在服务器上组织语言包**交由开发者自行决定，您完全可以根据自己的喜好来决定如何加载。
|
||||
`voerkaI18n`将编写**如何语言加载器**和**如何在服务器上组织语言包**交由开发者自行决定，您完全可以根据自己的喜好来决定如何组织语言包在服务器的位置以及如何加载，你甚至可以采用数据库来保存语言包，然后为之编写编辑界面，让用户可以自行修改。
|
||||
|
||||
|
||||
### 第四步：生成语言包文件
|
||||
@ -150,31 +150,31 @@ module.exports = {
|
||||
|
||||
### 第五步：编写语言包补丁
|
||||
|
||||
至此，我们已经实现了可以为应用动态添加语言支持的功能。但是默认语言加载器只是针对的未知的语言起作用，而对内置的语言是不起作用的。也就是说上例中的内置语言`cn`和`en`不能通过此方法来加载。
|
||||
至此，我们已经实现了可以为应用动态添加语言支持的功能。但是默认语言加载器只是针对的未知的语言起作用，而对内置的语言是不起作用的。也就是说上例中的内置语言`zh`和`en`不能通过此方法来加载。
|
||||
|
||||
在实际应用中，我们经常会在应用上线的，发现应用中的某此语言翻译错误，此时就可以利用`voerkaI18n`的语言包补丁特性来解决此问题。
|
||||
利用`voerkaI18n`的语言包补丁特性,您就可以随时修复翻译错误，而不需要重新打包应用。
|
||||
|
||||
`voerkaI18n`的语言包补丁特性的工作机制同样也是利用了默认语言加载器来加载语言包补丁。其工作原理很简单，如下：
|
||||
- 按上例中的方式注册默认语言加载器
|
||||
- 当i18nScope注册到全局VoerkaI18n时，会调用默认的语言加载器,从服务器加载语言包，然后合并到本地语言包中，这样就很轻松地实现了动态言包的特性。
|
||||
- 当`i18nScope`注册到全局`VoerkaI18n`时，会调用默认的语言加载器,从服务器加载语言包，然后**合并到本地语言包中**，这样就很轻松地实现了为语言包打补丁的功能。
|
||||
|
||||
在本例中，我们假设chat应用的中文语言发现翻译错误，需要一个语言包补丁来修复，方法如下：
|
||||
在本例中，我们假设`chat`应用的中文语言发现翻译错误，需要一个语言包补丁来修复，方法如下：
|
||||
```javascript | pure
|
||||
webroot
|
||||
|-- languages
|
||||
<chat>
|
||||
|-- cn.json
|
||||
|-- zh.json
|
||||
|
||||
```
|
||||
按上例说明的方式，在服务器上编辑一个`cn.json`文件，保存到`languages/char/cn.json`，里面内容只需要包括出错的内容即可。
|
||||
按上例说明的方式，在服务器上编辑一个`zh.json`文件，保存到`languages/char/zh.json`，里面内容只需要包括出错的内容修复即可，其会自动合并到目标语言包中，整个过程对用户是无感的。
|
||||
|
||||
```javascript | pure
|
||||
{
|
||||
"4": "名称空间"
|
||||
}
|
||||
```
|
||||
然后，当应用切换到指定`cn`语言时，就会下载该语言包合并到源码中的语言包，从而实现为语言包打补丁的功能，修复翻译错误。此功能简单而实用，强烈推荐。
|
||||
然后，当应用切换到指定`zh`语言时，就会下载该语言包合并到源码中的语言包，从而实现为语言包打补丁的功能，修复翻译错误。**此功能简单而实用，强烈推荐。**
|
||||
|
||||
### 小结
|
||||
|
||||
@ -220,7 +220,9 @@ i18nScope.registerDefaultLoader(async (language,scope)=>{
|
||||
</div>
|
||||
```
|
||||
|
||||
还是以本例来说明，上面的Vue应用是无法枚举出来`de`语言的，这就需要应用自己处理，比如：
|
||||
还是以本例来说明，上面的Vue应用是无法枚举出来`de`语言的，因为这是在开发阶段时未定义的。
|
||||
|
||||
我们需要UI做简单的扩展，以便能在未来动态添加语种时能进行切换，比如：
|
||||
|
||||
```html
|
||||
<template>
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
虽然`VoerkaI18n`推荐采用`t("中华人民共和国万岁")`形式的符合直觉的翻译形式，而不是采用`t("xxxx.xxx")`这样不符合直觉的形式，但是为什么大部份的国际化方案均采用`t("xxxx.xxx")`形式？
|
||||
|
||||
在我们的方案中，t("中华人民共和国万岁")形式相当于采用原始文本进行查表，语言名形式如下：
|
||||
在我们的方案中，`t("中华人民共和国万岁"`)`形式相当于采用原始文本进行查表，语言名形式如下：
|
||||
|
||||
```javascript | pure
|
||||
// en.js
|
||||
@ -34,7 +34,7 @@
|
||||
|
||||
如此，就消除了在`en.js`、`jp.js`文件中的冗余。但是在源代码文件中还存在`t("中华人民共和国万岁")`，整个运行环境中存在两份副本，一份在源代码文件中，一份在`idMap.js`中。
|
||||
|
||||
为了进一步减少重复内容，因此，我们需要将源代码文件中的`t("中华人民共和国万岁")`更改为`t("1")`，这样就能确保无重复冗余。但是，很显然，我们不可能手动来更改源代码文件，这就需要由`voerkai18n`提供的一个编译区插件来做这一件事了。
|
||||
为了进一步减少重复内容，因此，我们需要将源代码文件中的`t("中华人民共和国万岁")`更改为`t("1")`，这样就能确保无重复冗余。但是，很显然，我们不可能手动来更改源代码文件，这就需要由`voerkai18n`提供的一个编译期插件来做这一件事了。
|
||||
|
||||
以`babel-plugin-voerkai18n`插件为例，该插件同时还完成一份任务，就是自动读取`voerkai18n compile`生成的`idMap.js`文件，然后将`t("中华人民共和国万岁")`自动更改为`t("1")`，这样就完全消除了重复冗余信息。
|
||||
|
||||
@ -42,4 +42,4 @@
|
||||
|
||||
**注意：**
|
||||
|
||||
- 如果没有启用`babel-plugin-voerkai18n`或`vite`等编译区插件，还是可以正常工作，但是会有一份默认语言的冗余信息存在。
|
||||
- 如果没有启用`babel-plugin-voerkai18n`或`vite`等编译期插件，还是可以正常工作，但是会有一份默认语言的冗余信息存在。
|
||||
@ -1,8 +1,8 @@
|
||||
---
|
||||
title: 更新历史
|
||||
---
|
||||
# 更新历史
|
||||
# 更新日志
|
||||
|
||||
## 2022/8/7
|
||||
|
||||
- 更新文档
|
||||
## 2022/8/5
|
||||
|
||||
- 增加语言包补丁功能，可以在应用上线后动态更新修复翻译错误
|
||||
|
||||
@ -1,10 +1,11 @@
|
||||
# 命令行工具
|
||||
|
||||
`@voerkai18n/cli`命令行工具用来实现工程初始化、扫描提取文本、自动翻译和编译语言等功能。
|
||||
|
||||
<Alert type="error">
|
||||
<b>建议将<code>@voerkai18n/cli</code>命令行工具安装在全局</b>
|
||||
</Alert>
|
||||
|
||||
::: info
|
||||
建议将`@voerkai18n/cli`命令行工具安装在全局
|
||||
:::
|
||||
|
||||
## 安装
|
||||
|
||||
@ -65,13 +66,20 @@ Options:
|
||||
|
||||
运行`voerkai18n init`命令后，会在当前工程中创建相应配置文件。
|
||||
|
||||
```javascript | pure
|
||||
myapp
|
||||
|-- languages
|
||||
|-- settings.json // 语言配置文件
|
||||
|-- package.json
|
||||
|-- index.js
|
||||
```
|
||||
<Tree title="myapp">
|
||||
<ul>
|
||||
<li>
|
||||
languages
|
||||
<small>多语言目录</small>
|
||||
<ul>
|
||||
<li>settings.json</li>>
|
||||
</ul>
|
||||
</li>
|
||||
<li>index.md</li>
|
||||
<li>package.json</li>
|
||||
<li>...</li>
|
||||
</ul>
|
||||
</Tree>
|
||||
|
||||
`settings.json`文件很简单，主要是用来配置要支持的语言等基本信息。
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user