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配置表

注意事项

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是设置了自动保存的，而你边敲代码边自动保存触发了重新编译，就会触发收录中文词条，收录到了新的中文词条就会触发了翻译，若你保存次数很多很快，...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Hotfix

hotfix

Hotfix

feature

hotfix

i18n-auto-webpack

Usage

安装

配置loader

watch

name

dependency

注意事项

配置plugin

配置翻译

获取`secretId`和`secretKey`

翻译api的限制

Releases: pekonchan/i18n-auto-webpack

v0.5.5

Hotfix

v0.5.4

hotfix

v0.5.3

Hotfix

v0.5.2

feature

hotfix

v0.4.0

v0.3.0

第一版v0.2.1

i18n-auto-webpack

Usage

安装

配置loader

watch

name

dependency

注意事项

配置plugin

配置翻译

获取secretId和secretKey

翻译api的限制

获取`secretId`和`secretKey`