i18n-auto-webpack v0.5.2

i18n-auto-webpack

• English Document

使用该工具包可以帮助你以自动化形式完成国际化工作，能够自动地收集中文词条、替换代码为指定的国际化转换函数、自动翻译等功能。

它不单单可以对中文进行国际化，还可以按照你指定的语言来进行工作。

注意该工具在编译过程转换代码的，而不是永久性地替换代码，不具备破坏性

这个工具包主要分为两个主要部分

• loader。这是一个自定义的webpackloader，需要指定引入该loader以完成自动收集与替换代码主要功能。
• plugin。这是一个自定义webpackplugin，需要使用该插件以完成生成词条配置文件的功能。

使用的方法也就是webpack对loader和plugin的使用方法。

需要注意，该工具不包含实现国际化转换函数。每个项目采用的语言框架不一样，各自采用的转换函数调用方式也都不一样，该工具是要搭配国际化转换函数一起使用的。如你项目是vue，可使用vue-i18n，React的react-intl和react-i18next，angular的ngx-translate，或者自己实现转换函数等等。i18n-auto-webpack只提供收录词条、替换代码为指定的国际化转化函数、以及翻译词条能力（除非你就是想单独使用这些能力）。

这里说的转换函数，如vue-i18n的$t之类的方法

Usage

安装

npm i i18n-auto-webpack

在工程项目根目录下创建全局配置文件i18nauto.config.js

const {resolve} = require('path')
const rootPath = process.cwd()

module.exports = {
    // 中文词条的配置文件
    entry: {
        filename: 'zh.json', // 文件名（不含目录路径）
        path: resolve(rootPath, './lang') // 文件所在绝对目录（不含文件名）
    },
    // 翻译配置
    translate: {
        on: true, // 是否开启翻译
        lang: ['en'], // 要翻译成哪些语言
        path: resolve(rootPath, './lang'), // 生成的翻译文件所在目录
        secretId: 'your secretId', // 必填。翻译api所需的你用户信息secretId 
        secretKey: 'your secretKey' // 必填。翻译api所需的你用户信息secretKey
    }
}

entry是指定根据已有的中文词条配置表基础上更新收集的词条，没有的话直接创建。

例如你项目里已经存在一份中文词条配置文件，抑或是你之前就已经利用该工具生成过一份配置文件了，接下来的开发是需要基于这份已有的文件进行更新新增或被删除的词条。

默认情况下，收集完成后同样会更新到entry指定路径的文件中。即这个文件既被用来作为收集词条的基础，又被作为最终生成的配置文件。若指定路径文件不存在，会自动创建该文件。

特殊情况下，假设你有需要生成配置文件到不同于entry的地方，那么可以指定output字段，该字段默认值就是entry，你也可以自己指定。但是值得注意的是，当你指定了一个不同于entry的值，若entry和output的文件不能保持一样，就会每次收集词条就会把output里比entry多的词条视为新增的词条，就会触发重新生成配置文件，所以当你毅然选择指定output，请保持手动同步更新到entry文件中（当然你有另外用途需要区分开来除外）。 因此我的建议是，没啥特殊情况，就只使用一个entry字段就好了

i18nauto.config.js更多配置规则请查阅i18nauto.config.js配置表

translate翻译设置部份，需要有更多的说明，请查阅配置翻译

配置loader

在webpack的配置中进行如下设置

exports.export = {
    module: {
        rules: [
            {
                test: /\.js$/,
                loader: 'i18n-auto-webpack/loader',
                options: {
                    watch: true,
                    name: 'i18n.t',
                    dependency: {
                        name: 'i18n',
                        value: 'src/common/i18n.js'
                    }
                }
            }
        ]
    }
}

对什么文件内的中文要进行收录，就对这些文件使用工具的loader，引用的loader路径为i18n-auto-webpack/loader。

例子中options选项的为基础常用的配置：

watch

是否监听更新，若设置true，则开发者编写代码每触发一次热更新，就收集一次代码中新增的中文词条替换代码。若设置为false，则只对第一次启动工程构建的文件进行收集词条替换代码，后续开发中新增的不会对新增的词条进行代码替换。默认为false。 可多个loader使用不同的watch。

name

国际化语言切换函数的调用路径。例如你原本想要替换代码中的中文词条为国际化语言切换函数，怎么调用这个函数就传什么，例如i18n.t('001')，虽然最终执行的是t函数，但是你调用这个t需要通过i18n这个对象，那么完整的调用路径即为i18n.t，所以name要传i18n.t。

dependency

国际化语言切换函数所需的依赖。例如i18n这个对象的内容是封装在这个src/common/i18n.js文件中导出的，要进行切换，需要用到i18n这个对象里的t函数。那么dependency就有两种写法:

// 写法一
options: {
    name: 'i18n.t',
    dependency: {
        name: 'i18n',
        value: 'src/common/i18n.js'
    }
}

// 上述写法会最终生成代码 import i18n from 'src/common/i18n.js'
// 然后代码中将会使用i18n.t()进行切换语言

// 写法二
options: {
    name: 't'
    dependency: {
        name: 't',
        objectPattern: true, // 表示解构形式
        value: 'src/common/i18n.js'
    }
}

// 上述写法会最终生成代码 import { t } from 'src/common/i18n.js'
// 然后代码中将会使用t()进行切换语言

loader更多配置请查阅 loader配置表

如果你出现首次运行该工具收集的词条是正常的，但是后续再次收集发现少了，那么可能是受限于构建脚手架或者webpack某个版本的影响，对编译结果进行了缓存，导致无法收集。你可尝试禁用webpack的cache-loader缓存看看，如下所示

 // 禁用缓存 
 // webpack-chain写法
config.module.rule('vue').uses.delete('cache-loader');
config.module.rule('js').uses.delete('cache-loader');
config.module.rule('ts').uses.delete('cache-loader');

注意事项

i18n-auto-webpack/loader预期接收的代码是Javascript内容，它的工作原理是对传递进来的是Javascript代码解析成AST，然后分析AST查找提取中文等系列操作后再转回去Javascript代码。

所以当你若要对一个非Javascript内容的文件使用i18n-auto-webpack/loader时，请在其他loader将其转化为Javascript后使用，请确保loader的执行顺序。

例如.vue文件，你想收录.vue文件里template和script部份的中文词条，则要对.vue文件使用i18n-auto-webpack/loader。

// webpack config file

const i18nAutoLoaderOptions = {
    watch: true,
    name: 'i18n.t',
    dependency: {
        name: 'i18n',
        value: 'src/common/i18n.js'
    }
}

// 针对vue-loader v14版本
module.exports = {
    module: {
        rules: [
            // 在原本使用vue-loader的那个规则上新增它的options配置，加上对'i18n-auto-webpack/loader'的处理
            {
                test: /\.vue$/,
                use: [
                    {
                        loader: 'vue-loader',
                        options: {
                            postLoaders: {
                                // 这里是在template部份转化成render函数（js代码）后用'i18n-auto-webpack/loader'处理
                                html: {
                                    loader: 'i18n-auto-webpack/loader',
                                    options: {
                                        watch: true,
                                        name: '_vm'
                                    }
                                },
                                js: {
                                    loader: 'i18n-auto-webpack/loader',
                                    options: i18nAutoLoaderOptions
                                }
                            }
                        }
                    }
                ]
            }
        ]
    }
}

// 针对vue-loader v15版本
module.exports = {
    module: {
        rules: [
            // 这是原本对vue文件使用vue-loader的规则
            {
                test: /\.vue$/,
                loader: 'vue-loader'
            },
            // 针对vue文件里的template部分。这个要新起一个规则，不能用在原来使用`vue-loader`的那个规则里
            {
                test: /\.vue$/,
                resourceQuery: /type=template/,
                enforce: 'post',
                loader: 'i18n-auto-webpack/loader',
                options: i18nAutoLoaderOptions
            },
            // 原来对js文件使用的规则，同样会适用于vue文件里的script部份的js代码。
            {
                test: /\.js$/,
                use: [
                    {
                        loader: 'i18n-auto-webpack/loader',
                        options: i18nAutoLoaderOptions
                    },
                    {
                        loader: 'babel-loader'
                    }
                ]
            }
        ]
    }
}

// 针对vue-loader v16到目前最新版本

//在这个版本的vue-loader就很友好了，实际上你对js文件的规则配置也同样适用于vue文件里的script部份和template部份了。因此只需要在原来配置js文件的规则添加多一个i18n-auto-webpack/loader即可。
module.exports = {
    module: {
        rules: [
            {
                test: /\.js$/,
                use: [
                    {
                        loader: 'i18n-auto-webpack/loader',
                        options: i18nAutoLoaderOptions
                    },
                    {
                        loader: 'babel-loader'
                    }
                ]
            }
        ]
    }
}

你可能会看到这么多版本的vue-loader怎么使用我这个i18n-auto-webpack/loader还不同的写法，觉得好像好复杂似的。但是这并不是我这个loader的问题，我的loader负责的事情是很简单单一的，就是把Javascript的代码中找出中文替换而已。因此使用它的写法不同取决于它的上游loader，这是上游loader的责任，这里就是vue-loader的责任了，谁让它改版没有向前兼容。

理论上i18n-auto-webpack/loader是可以对任何前端框架或语言进行使用的，只要有合适的loader将其转换成Javascript后使用。

配置plugin

在webpack的配置中进行如下设置

import i18nAutoPlugin from 'i18n-auto-webpack/plugin'

module.exports = {
    plugins: [
        new i18nAutoPlugin({
            watch: true
        })
    ]
}

是否监听更新，若设置true，则开发者编写代码每触发一次热更新，就收集一次代码中新增的中文词条更新到配置文件中。若设置为false，则只对第一次启动工程构建的文件进行收录词条创建配置文件，后续开发中新增的不会更新到配置文件中。默认为false

plugin更多配置请查阅 plugin配置表

配置翻译

要开启自动翻译功能，需要在i18nauto.config.js中进行相应的设置。

const {resolve} = require('path')
const rootPath = process.cwd()

module.exports = {
    // 翻译的常用配置
    translate: {
        on: true, // 是否开启翻译
        lang: ['en'], // 要翻译成哪些语言
        path: resolve(rootPath, './lang'), // 生成的翻译文件所在目录
        secretId: 'your secretId' // 必填。翻译api所需的你用户信息secretId
        secretKey: 'your secretKey' // 必填。翻译api所需的你用户信息secretKey
    }
}

本工具采用的翻译api是腾讯翻译。至于为什么选择腾讯翻译，当然有做过各种翻译api的调研，最后发现还是腾讯翻译的api相对来讲使用起来会更加有优势（除去翻译结果外，谁更准我这英语业务水平不好判断）

当你项目有大量词条需要被翻译时，其实你更多的不会关心翻译出来的是否准确，基本差不了哪里去的。如果你觉得个别翻译不准，可自己手动在翻译出来生成的配置文件中修改就可以了。本身不论你是用哪个api，最终还是需要有一个人工的校正工作。

因为采用的是第三方的翻译api，现在所有的翻译api都是要求注册用户获取授权才能调用的，而且免费用户都是有使用额度的。所以要想使用这个工具的翻译能力，首先使用者需要去注册腾讯云的机器翻译，获取secretId和secretKey写在配置文件里。

可能有人就会问为啥我这个工具自身里面用注册过的用户身份去调取api，而要每个使用者自己提供用户身份。首先，大家可以去查一下，基本实现翻译的工具类库，都是会要求使用者提供用户身份Id的，不可能工具内部用一个帐号去帮大家调用api的，因为api是需要收费的，一个月内有免费的额度。如果大家都用一个帐号，那么这个费用就很高了，而且还要类库的开发者自己承担。其次，用户身份是很重要的，需要用户自己保管，类库开发者不能把用户身份信息暴露在源代码中。

出于安全考虑，当你的项目工程代码是公网公开的，请勿把你或你公司的帐号的secretId和secretKey直接写在i18nauto.config.js中，请使用环境变量进行替代，读取本地机器上的环境变量。或者是把i18nauto.config.js文件设置在.gitignore中进行git版本控制忽略。这样就不会存在别人盗用你的帐号的风险。

获取secretId和secretKey

先访问腾讯云控制台，进行注册登陆。

进入用户-用户列表，找到对应用户（若无则新建用户）。

点击进入用户详情，选择进入API密钥导航

可以看到截图左下角有个密钥列。这里面就可以找到secretId和secretKey了。

翻译api的限制

腾讯机器翻译api有两个限制需要我们留意下的：

• 文本翻译的每月免费额度为5百万字符。
• 1秒内请求api不得超过5次。

其实一般来讲，每月免费额度为5百万字符是够用的，一个项目中中文大部份应该不会超过5百万字符，假设真的超过了，可以考虑分月分批翻译。

为了让使用者用该工具更安心，我这边提供了两个配置项用于设置当翻译超过你指定的字符数限制时，停止调用翻译api。具体可查看 startTotal和endTotal说明

注意这个数量，是按照翻译语言种类来统计的。例如“你好啊”这个要翻译成英文和德文，那么就是 3 * 2 = 5，这个就消耗了5个字符的额度了。 3是中文的字符数，2的翻译成两个语种。

而第二个限制，i18n-auto-webpack这个工具内部已经实现了节流以满足这个条件要求。但是正因为此举，假设你的编码IDE是设置了自动保存的，而你边敲代码边自动保存触发了重新编译，就会触发收录中文词条，收录到了新的中文词条就会触发了翻译，若你保存次数很多很快，就会频繁触发翻译接口，而i18n-auto-webpack因为做了节流处理，就会可能导致翻译没那么实时，这是无法避免的。加上我们敲代码可能会输错或者来回改动，触发翻译越多，翻译字符数量也会上升，而免费额度只有5百万字符。

因此，对于这两个限制条件来讲，要开启自动翻译功能，我的建议是 1. 要么你的编码IDE设为手动保存减少频繁触发热更新；（最佳实践） 2. 要么把loader和plugin部分的watch配置设置为false，不要实时监听变化而更新； 3. 要么把自动翻译功能关闭，选择i18n-auto-webpack提供的单独翻译能力i18n-auto-webpack/translate方法，编写命令，在你想要翻译的时候手动触发该命令进行翻译。（最稳妥方案）

关于使用单独的翻译能力，请查阅下面的独立翻译函数介绍

至此，上述介绍的配置，是可以快速实现自动化国际化的简单配置。若想了解更多功能和定制化，可继续查阅下属的详细配置表

独立翻译函数

使用i18n-auto-webpack/translate提供的能力，能够单独编写脚本实现翻译能力。

这样就能够依赖它来编写nodejs脚本，然后写在npm script里写个命令，专门在开发者基本编写好代码后，运行命令做最后的统一翻译。这样就可以关闭自动翻译，能规避翻译api的条件限制导致的一些问题（见上节内容翻译api的限制）

或者你已经做好国际化的方案了，已经实现了代码替换和收录中文了，剩下的就只有翻译工作还没做，还没生成翻译语言的配置文件，那么你也可以使用i18n-auto-webpack/translate来帮你完成这一步工作。

如果想单独使用这个翻译能力，仍然需要配合i18nauto.config.js文件使用，需要设置翻译接口所需的你的secretId和secretKey

使用示例

// 引入翻译方法
const { createTranslate } = require('i18n-auto-webpack/translate')

const path = require('path')

// 翻译的目标配置
const target = {
    path: path.resolve(__dirname), // 翻译的结果放在哪个目录中
    lang: ['en'] // 要翻译出来的语言
}
// 翻译的源内容配置
const source = {
    path: path.resolve(__dirname, 'zh.json') // 根据哪个中文配置文件来生成对应的国际化语言配置文件
}

// 执行该方法后翻译结果会自动创建/修改到指定的目录中
createTranslate(target, source)

入参

方法的参数功能介绍：

一共三个入参，按顺序如下 target, source, needFile

关于<Obejct>target：

关于<Obejct>source：

关于needFile

Booealn类型，默认是true。

代表是否需要把翻译的结果生成到指定的目录中

• 若存在同名文件，则会根据已存在的文件内容来判断哪些中文需要进行翻译，然后把翻译结果合并到该文件里。
• 若不存在同名文件，则会直接把所有中文翻译后创建出来。

返回值

返回的是Promise。返回的回调结果是一个对象，以翻译的语言为key，翻译结果为value，如

en: {
    1: 'hello',
    2: 'Who am i'
}

单独的能力

使用i18n-auto-webpack可以使用它的完整功能，但是可能有部分人仅仅是看中了该工具的其中某个能力，而不需要使用它的全部功能。

仅收录中文词条

开发者有需求仅仅是想收录项目代码中的中文词条，生成配置文件，而不需要转换代码中的中文词条，不想通过编译时转换代码这种方式。

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

module.exports = {
    module: {
        rules: [
            {
                test: /\.js$/,
                loader: 'i18n-auto-webpack/loader',
                options: {
                    transform: false
                }
            }
        ]
    }
}

仅使用翻译能力

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

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

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

具体使用方法可参考独立翻译函数

生成映射文件

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

那么可以设置sourceMap: true达到该目的。

const i18nAutoPlugin = require('i18n-auto-webpack/plugin')
module.exports = {
    plugins: [
        new i18nAutoPlugin({
            sourceMap: true
        })
    ]
}

特殊情况

个别不需要国际化

当代码中某些词条是不需要国际化的，那么可以在词条前添加行内块状注释的形式，单独指明该词条不需要国际化，如：

const word = /*no-i18n-auto*/ '你好';

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

代码中仍需写转换函数时

当你有不得不需要在代码中直接使用国际化转换函数的时候，你仍然可以放心大胆使用。例如

// i18n.tc是国际化转换函数
const word = i18n.tc('1')

对应的词条表中是

// zh.json
{
    "1": "你好"
}

i18n-auto-webpack会自动根据你在loader中设置的国际化转换依赖的name值来判断你调用的方法是否为国际化转换函数，是的话，词条表中会为你保留对应的词条，而不会说因为代码中没有这个中文，会在词条表中删除对应的词条。当然，这时候你需要自己手动在词条表中设置对应的词条了。

module.exports = {
    module: {
        rules: [
            {
                test: /\.js$/,
                use: [
                    {
                        loader: 'i18n-auto-webpack/loader',
                        options: {
                            watch: true,
                            name: 'i18n.tc', // 就是这个名字来判断
                            dependency: {
                                name: 'i18n',
                                value: 'src/common/i18n.js'
                            }
                        }
                    }
                ]
            }
        ]
    }
}

这种场景更多是的，你需要使用国际化转换函数传递更丰富的参数完成更丰富的能力、或者是带有html标签的字符串需要直接渲染出来的（类似vue的v-html），如果你不自己处理成写成国际化转换函数的形式，那么就会把html的标签也当成词条的一部分进行提取和翻译，可能会破坏你的逻辑。

若你使用国际化转换函数不仅仅是用name指定的方式调用，还有其他方式调用， 你也想保留对应的key的词条，那么可以使用alias配置，指定它的其他调用方式。例如使用了vue-i18n，可以直接在组件中用this.$t()来调用转换，此时你可设置alias: ['$t', '_vm.$t']来保留调用它的key对应的词条：

{
    loader: 'i18n-auto-webpack/loader',
    options: {
        watch: true,
        name: 'i18n.tc',
        alias: ['$t', '_vm.$t'],
        dependency: {
            name: 'i18n',
            value: 'src/common/i18n.js'
        }
    }
}

此时代码中使用i18n.tc和$t的方法内key对应的词条都将保留。

此外，

使用i18n-auto-webpack是一个提高工作效率的工具，也能相对成功找到代码中中文的词条进行替换，但是各种开发者写的各种代码，会存在各种可能性，我这边只能说把大部分常规场景都囊括进来，若你遇到特殊的写法或场景，使用该工具无法成功提取到中文，请告诉我，我将进行补充，或者你可能需要调整为直接在代码中使用国际化转换函数的写法。项目代码中存在直接使用国际化转换函数+中文（i18n-auto-webpack帮忙收录国际化）的场景是无法避免的。

详细配置表

i18nauto.config.js

关于startTotal和endTotal

因为腾讯翻译api一个月有免费的翻译文本数量限制，最多5百万字符，若超出，则需要付费了。所以startTotal和endTotal的设置会让你使用得更安心些。注意，startTotal只会从本次启动服务（如启动了dev-server）基于它进行累计计算。我们并不会知道之前的服务你使用了多少额度，所以你可能每次启动服务的时候都需要修改这个startTotal

可惜的是腾讯机器翻译api暂时还没有api可以查询用户使用额度

关于translate下的子属性，从secretId开始，都是遵循腾讯云翻译api的要求的配置。若想了解更多，可查阅 腾讯云翻译api文档

loader

plugin

不论怎样，第一次启动项目，如开发环境下启动项目，或打包生产环境，必然会根据实际情况需要看是否更新一次词条配置表。

最后

如果大家感兴趣的话，使用它时遇到什么问题，欢迎提问题，我将尽最大能力为大家解答。

喜欢的话，麻烦github上点个Star吧，谢谢大家