Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
pekonchan committed Sep 16, 2023
1 parent 2ce48f5 commit 56d2fcd
Showing 1 changed file with 46 additions and 3 deletions.
49 changes: 46 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,7 @@ module.exports = {
}
```
是否监听更新,若设置`true`,则开发者编写代码每触发一次热更新,就收集一次代码中新增的中文词条更新到配置文件中。若设置为`false`,则只对第一次启动工程构建的文件进行收录词条创建配置文件,后续开发中新增的不会更新到配置文件中。默认为`false`
若你需要手动更改中文词条配置文件(处于校验阶段,或第一次使用预料着可能需要手动调整更正),建议不要开启`watch`,不然可能覆盖你的调整。

plugin更多配置请查阅 [plugin配置表](https://github.com/pekonchan/i18n-auto-webpack#plugin)

Expand Down Expand Up @@ -311,7 +312,7 @@ module.exports = {

为了让使用者用该工具更安心,我这边提供了两个配置项用于设置当翻译超过你指定的字符数限制时,停止调用翻译api。具体可查看 [startTotal和endTotal说明](https://github.com/pekonchan/i18n-auto-webpack#i18nautoconfigjs)

> 注意这个数量,是按照翻译语言种类来统计的。例如“你好啊”这个要翻译成英文和德文,那么就是 3 * 2 = 5,这个就消耗了5个字符的额度了。 3是中文的字符数,2的翻译成两个语种。
> 注意这个数量,是按照翻译语言种类来统计的。例如“你好啊”这个要翻译成英文和德文,那么就是 3 \* 2 = 6,这个就消耗了6个字符的额度了。 3是中文的字符数,2的翻译成两个语种。
而第二个限制,`i18n-auto-webpack`这个工具内部已经实现了节流以满足这个条件要求。但是正因为此举,假设你的编码IDE是设置了自动保存的,而你边敲代码边自动保存触发了重新编译,就会触发收录中文词条,收录到了新的中文词条就会触发了翻译,若你保存次数很多很快,就会频繁触发翻译接口,而`i18n-auto-webpack`因为做了节流处理,就会可能导致翻译没那么实时,这是无法避免的。加上我们敲代码可能会输错或者来回改动,触发翻译越多,翻译字符数量也会上升,而免费额度只有5百万字符。

Expand Down Expand Up @@ -401,7 +402,11 @@ en: {
### 仅收录中文词条
开发者有需求仅仅是想收录项目代码中的中文词条,生成配置文件,而不需要转换代码中的中文词条,不想通过编译时转换代码这种方式。

**适合场景:** 不需要翻译,有专人翻译,并且你不想使用编译构建时转译代码,想直接写在源码中进行词条转换,而你不想人工收集本地词条,可用本工具完成收集工作

那么就可以在使用`i18n-auto-webpack/loader`时设置`transform: false`

对转换的文件设置`transform: false`,这里以js文件的配置为例子:
```javascript
module.exports = {
module: {
Expand All @@ -417,16 +422,51 @@ module.exports = {
}
}
```
plugin的设置还是需要的

### 仅使用翻译能力
若你已经实现了国际化方案,你已经做好了收录中文词条和转换代码的工作了,剩下的也只是想要把自己收录好的中文翻译成其他语言,还差这一步工作。

或者你正在寻找一个类库想实现翻译功能,去做别的需求。

**适合场景:** 你的项目里已有词条配置文件了,代码里也做好了转换,现在仅仅差各个语言的词条配置文件,即你只想实现翻译。

那么`i18n-auto-webpack/translate`可以帮到你,我把该工具使用到的翻译能力单独抽离出来,可以当成独立的类库进行使用。

具体使用方法可参考[独立翻译函数](https://github.com/pekonchan/i18n-auto-webpack#%E7%8B%AC%E7%AB%8B%E7%BF%BB%E8%AF%91%E5%87%BD%E6%95%B0)

因为翻译需要用腾讯机器翻译的用户信息,该部分信息可能不适合进行git版本的管理。考虑到这点,该工具支持项目本地创建`local.i18nauto.config.js`来区分于`i18nauto.config.js`,它的优先级更高,所以你的一些私人配置可写在`local.i18nauto.config.js`上,再用`.gitignore`屏蔽掉它即可。

### 仅使用编译转换代码能力
若你只想根据将代码中需要国际化的词条转换成国际化转换函数的依赖使用,其他能力不需要(自动翻译配置、自动生成收集源码词条配置、生成source map)

**适合场景:** 不需要翻译,有专人翻译,也有维护好的源码词条配置文件,后续的词条文件更新也是人工维护的,而你想自动根据已有的词条配置文件完成词条之间的代码转换。

对转换的文件设置`fallback: true`以及`watch: false`,这里以js文件的配置为例子:

```javascript
module.exports = {
module: {
rules: [
{
test: /\.js$/,
loader: 'i18n-auto-webpack/loader',
options: {
watch: false,
fallback: true,
name: 'i18n.t',
dependency: {
name: 'i18n',
value: 'src/common/i18n.js'
}
}
}
]
}
}
```
仅需要设置loader,不需要plugin

### 生成映射文件
当你有需求想要知道项目里的哪些文件有中文词条,有什么中文词条,而且它在该文件中出现的次数是多少。

Expand All @@ -446,15 +486,15 @@ module.exports = {

### 个别不需要国际化
当代码中某些词条是不需要国际化的,那么可以在词条前添加行内块状注释的形式,单独指明该词条不需要国际化,如:
```
```js
const word = /*no-i18n-auto*/ '你好';

new Error(/*no-i18n-auto*/ '报错了');
```

### 代码中仍需写转换函数时
当你有不得不需要在代码中直接使用国际化转换函数的时候,你仍然可以放心大胆使用。例如
```
```js
// i18n.tc是国际化转换函数
const word = i18n.tc('1')
```
Expand Down Expand Up @@ -548,6 +588,8 @@ module.exports = {
关于`translate`下的子属性,从`secretId`开始,都是遵循腾讯云翻译api的要求的配置。若想了解更多,可查阅 [腾讯云翻译api文档](https://cloud.tencent.com/document/api/551/40566)

> 本地可同样新建一个`local.i18nauto.config.js`文件,如果本地项目中既存在`i18nauto.config.js`又存在`local.i18natuo.config.js`,那么以`local.i18nauto.config.js`为准。该文件设立的初衷是,假设你有一些本地配置不想上传到`git`,例如翻译的你个人用户`secretId``secretKey`,你不希望上传上去被共享,那么可以先用`.gitignore`问价把`local.i18nauto.config.js`屏蔽了,然后在该文件上写上你的私人配置
### loader
| 配置项 | 描述 | 类型 | 必填 | 默认值 |
| ---------- | ------------------------------------------------------------ | ------- | -------------------------- | ------ |
Expand All @@ -561,6 +603,7 @@ module.exports = {
| `alias` | 替换代码中词条的实现国际化的函数调用完整路径名的别称。数组元素支持字符串和正则表达式 | Array || |
| `watch` | 是否实时监听文件变化,实时更新对应于配置表中的key值 | Boolean || false |
| `transform` | 是否需要转换代码。若你仅仅想收录项目中的词条,而不转换代码,可设置为false | Boolean || true |
| `fallback` | 当在词条配置文件中找不到,即新加的词条,是否保持原状,即不转译词条。true为开启不转译新词条。适合人工维护词条配置文件的场景 | Boolean || false |

### plugin
| 配置项 | 描述 | 类型 | 必填 | 默认值 |
Expand Down

0 comments on commit 56d2fcd

Please sign in to comment.