超实用！一个命令搞定 Web 国际化

2021-08-26 腾讯 qiangwu

作者：qiangwu，腾讯CSIG Web开发工程师

i18n-helper-cli 是什么

i18n-helper-cli 是一个 Web 国际化整体解决方案，包含自动包裹词条，提取词条，翻译词条，词条翻译统计，节省人力预估统计，网页多语言显示异常检测（Coming soon）等功能。可以大大减低开发，测试，翻译各个角色的人力成本，减少重复劳动，低级错误。

为什么需要 i18n-helper-cli

Web 国际化流程

简单来说可以分为以下 5 个步骤

【选型】多语言框架选型（这里不深究，不在此篇范围），我们选定 i18next，18n-helper-cli 对多语言框架并不限制
【开发 - 包裹词条】从上面这步骤，我们知道需要把词条包裹起来 e.g 你好 => t('你好')
【开发 - 提取词条】把上一步中包裹的词条 copy 到翻译文件中
【翻译 - 翻译】翻译把词条翻译好，填入翻译文件
【测试 - 测试页面】开发提交测试后，对多语言页面进行测试

问题

通过上面 5 步，可以完成站点国际化。大多数场景大家就是这么做的，但这里充斥着大量人工劳动，大量人工劳动意味着重复低效，出错几率提高。让我们从以下三个阶段分析下这些问题

【开发阶段】人工操作包裹和提取词条耗时长，但对个人无任何成长。如果是【全新开发】的站点，大家还可以耐着性子包裹词条，提取词条，但如果是【存量修改】及对已有的站点做国际化，而且这里的页面几十上百，甚至更多，这里的包裹词条，提取词条的工作量会让人崩溃遗漏包裹，提取词条(代码多，词条隐藏在各个文件的各个角落里。。。) 提取词条后，运行多语言界面无法看到效果，需要等到翻译返回
【翻译阶段】翻译耗时长遗漏翻译
【测试阶段】多语言页面测试每个都要测，耗费大量时间遗漏测试某个多语言页面

所以这里最大的问题是上面这些工作都需人工操作，问题清楚了，那接下来我们要做的就是把这些人工操作能够交给机器，实现自动化，提高效率，降低出错几率。

解决方案

先上结论，i18n-helper-cli 可以很好的解决上述问题。

原理

整体方案

【词条包裹】通过对代码进行编译，得到AST，找到符合条件（中文，或者其他语言，可配置）的 Node，根据配置创建新 Node，替换老的 Node
【词条提取】同上，也是AST, 找到的符合条件的词条以及原代码已经包裹的词条会被一起提取，根据配置写入文件
【词条翻译】从源文件翻译：如果有一份翻译词库（这里有常见的翻译），我们提取出来的未翻译词条在这里有，我们就可以直接从这里翻译机器翻译：未翻译词条调用云服务实现翻译（这里我们用的是腾讯云的翻译服务）
【网页多语言显示异常检测】提供一份页面 url 列表，用 Cypress 进行截图，调用腾讯云 OCR 服务提取图片文字，进行对比，假设我们有个叫你好的词条翻译成 en 为Hello，如果我们通过 OCR 得到的是Hel，那么我们可以认为这个页面有问题（Coming soon）
【统计】翻译词条统计：根据当前语言下未翻译词条数 / 词条总数减低人工耗时预估：根据包裹，提取，翻译词条数预估

包裹词条方案详解

接下来我们详细分析下词条包裹的方案。我们要实现的是类似你好 => t('你好')，所以：

找到你好
替换成t('你好')

哈哈，刚说的就像网上的经典问题: 如何把大象放到冰箱?

回答：先打冰箱门，然后把大象放进去，在关上冰箱门

听起来没问题，好像很有道理的样子，但没有任何实际价值。言归正传，我们来探讨下实际解决方案：

方案 1 - 正则

针对匹配到中文，这里我们第一个想法应该就是正则表达式了。/[u4e00-u9fa5]可以匹配中文。至此，我们完成了第一步找到需要包裹的文字。接下来就是把包裹上了'你好'.replace(/([u4e00-u9fa5]+)/gi,'t('$1')')，搞定。慢着，真的这么简单吗，想想我们真实代码的情况，注释，各种复杂的模板字符串，换行等等。这意味着这个正则到后面会巨复杂，到后面会面对一个晦涩难懂，难于维护的正则表达式。

另外还有个很蛋疼的事情，比方说我们的调试，上报等等代码，如console.log('不需要提取')，怎么办？感觉脑子不够用了。

方案 2 - AST

我们希望只匹配我们想要的词条。比如下如下代码，我们预期匹配你好（注释和 console.log 的里的都不需要），如果有个方式只给到我们你好，然后我再判断它是不是包含中文，再包裹就再好不过了。

// 这是一段注释
const word = '你好';
console.log('世界');

有没有这样的好事？答案是还真有。是时候上这张神图了

Babel 的工作流程主要分为以下 3 个阶段：

Parse阶段：词法分析 & 语法分析
Transform阶段：生成AST，抽象语法树
Generate阶段：生成代码

这里我们着重说下Transform阶段，AST 处理的核心要素：

babel-core 通过 transform 将代码字符串转换为 AST 树；
babel-types 一个强大的用于处理 AST 节点的工具库，它包含了构造、验证以及变换 AST 节点的方法；
visitor 当 Babel 处理 Node 时，以访问者的形式获取节点信息，并进行相关操作。这种方式是通过一个 visitor 对象来完成，在 visitor 对象中定义了对于各种节点类型函数，我们可以通过不同类型节点做出相应处理。

通过上述要素，我们既可以完成对 AST 的修改。下面我们看下这里的核心代码：

return {
      visitor: {
        StringLiteral(path: NodePath<tt.StringLiteral>) {
          let { value } = path.node;
          value = replaceLineBreak(value);

          if (needWrap(wrapCharacter, value)) {
            let newNode = t.CallExpression(t.Identifier(T_WRAppER), [
              combine(value),
            ]);

            path.replaceWith(newNode);
          }
        },
        CallExpression(path: NodePath<tt.CallExpression>) {
          switch (path.node.callee.type) {
            case 'MemberExpression': {
              const excludeFuncName = i18nConf.parsedExcludeWrapperFuncName;
              if (excludeFuncName.length > 0) {
                const names: string[] = [];
                const me = path.node.callee as tt.MemberExpression;
                getName(me, names);
                const MEName = names.reverse().join('.');
                if (excludeFuncName.includes(MEName)) {
                  path.skip();
                }
              }
              break;
            }
            default:
              break;
          }
        },
}

针对上面我们诉求的例子，当我们得到 AST 后

// 这是一段注释 - 实际上会被解析成 CommentLine 类型，我们的代码不处理，所以该什么样还是什么样
const word = '你好' - 你好被解析为StringLiteral，判断是中文，这时候我们再重新构造一个新的节点，替换老的及完成了包裹
console.log('世界') - console.log被解析为CallExpression，我们可以通过在配置文件中配置需要忽略的包裹的方法，如果解析到的方法名在配置中，则忽略掉，这样就不会出来这里的世界

至此，我们即可完成我们的诉求，完美的对符合我们需要的词条就行包裹。

题外话 - 如何编写自己的 babel 插件

通过上面 AST 的方案，我们可以看得出这里的功能很强大，业界eslint,prettier，webpack等等都是通过对源码进行分析，转换，生成实现各种各样的功能。

我们可以开发自己的插件，去做各种有意思的事情，比如说代码埋点，国际化方案等等。看到这里我想大家一定会有个问题：

上面说的代码转 AST 时的各种类型，我们怎么知道转成什么类型了呢？

答：https://astexplorer.NET/

2.另外这些类型如何构造新的节点？

答：https://babeljs.io/docs/en/babel-types

如何使用 i18n-helper-cli

实例

请参考 example

安装

注意：请确保 Nodejs 版本大于 14！！！

# npm 安装
npm install i18n-helper-cli -D
# yarn 安装
yarn add i18n-helper-cli —dev

快捷使用

在项目根目录下生成 i18n.config.json 文件

# 交互式命令行
i18n-helper init
# 生成默认配置文件，具体参见【配置说明】（ 推荐大家用这个哈，交互方式的的后面加了不少配置还没来得及补齐）
i18n-helper init -y

包裹 & 提取 & 翻译 & 统计

# 包裹 & 提取 & 翻译 & 统计 i18n.config.json 中 srcPath 文件中的中文词条
i18n-helper scan -wetc

切换 Cli 语言

# cli 默认为中文，支持语言切换，目前支持zh & en
i18n-helper switch en

命令详情

# 包裹 & 提取 & 翻译 & 统计 i18n.config.json 中 srcPath 文件中的中文词条
# w:wrap e:extract t:translate tm: translate machine c:count
# l:language
# 这 5 个操作可以随意组合 e.g. i18n-helper scan -we 则只会翻译 & 提取
i18n-helper scan -wetc
i18n-helper scan -we -tm -c
# 包裹 & 提取 & 翻译 & 统计 指定路径，指定语言内符合规则的词条
# e.g i18n-helper scan -wetc -l en ./src/test/index.js
i18n-helper scan -wetc -l [language] [filepath]
i18n-helper scan -we -tm -c -l [language] [filepath]

# 包裹 i18n.config.json 中 srcPath 文件中的中文词条
i18n-helper wrap
i18n-helper scan -w
# 包裹指定文件中的中文词条
i18n-helper wrap [filepath]
i18n-helper scan -w [filepath]

# 提取 i18n.config.json 中 srcPath 文件中的中文词条到所有配置语言文件
i18n-helper extract
i18n-helper scan -e
# 提取指定文件中文词条到指定语言文件
# e.g i18n-helper extract -l en ./src/test/index.js
i18n-helper extract -l [language] [filepath]
i18n-helper scan -e -l [language] [filepath]

# 翻译 i18n.config.json 中配置翻译文件词条， -m 腾讯翻译君机器翻译
# 从翻译源文件文件中翻译
i18n-helper translate
i18n-helper scan -t
# 腾讯翻译君自动翻译
i18n-helper translate -m
i18n-helper scan -tm
# 翻译指定语言
# 从翻译源文件文件中翻译
i18n-helper translate [language]
i18n-helper scan -t -l [language]
# 腾讯翻译君自动翻译指定语言文件
i18n-helper translate -m [language]
i18n-helper scan -tm -l [language]

# 统计 i18n.config.json 中翻译文件的翻译情况
i18n-helper count
i18n-helper scan -c
# 统计指定语言翻译文件的翻译情况，多个语言用,分隔
i18n-helper count [language]
i18n-helper scan -c -l [language]

配置详情

module.exports = {
  // cli 语言
  cliLang: 'zh',
  // 项目类型：react | vue | js
  projectType: '[react]',
  // 默认包裹和提取词条的目录
  srcPath: './',
  // 扫描文件格式
  fileExt: 'js,ts,tsx',
  // 包裹的字符集，下面是中文
  wrapCharacter: '[u4e00-u9fa5]',
  // 包裹词条的名字
  wrapperFuncName: 't',
  // 忽略掉包裹的方法，多个用,分隔
  excludeWrapperFuncName: 'console.log,console.error',
  // jsx中的文字包裹方式，true用<trans></trans>， false用【wrapperFuncName】的value包裹
  jsx2Trans: false,
  // 当文件需要翻译时引入的文件
  importStr: `import {t} from './i18n;';n`,
  // 排除目录，此目录下的不会不会执行包裹和提取词条操作
  exclude: 'node_modules,dist,git',
  // 翻译词条目录
  localeDir: './locales',
  // 翻译语种
  languages: 'zh,en',
  // 源语言
  sourceLanguage: 'zh',
  // 翻译词条文件名
  transFileName: 'translation',
  // 翻译词条文件格式: json, po
  transFileExt: 'json',
  // 翻译词库目录（自动翻译目录）
  targetTransDir: './translations',
  // 翻译词库文件名
  targetTransFile: 'sourceTranslation.json',
  // 腾讯云 secretId
  secretId: '',
  // 腾讯云 secretKey
  secretKey: '',
};

未来规划

[ ] 网页多语言显示异常检测
[ ] 丰富提取文件(po, csv, Excel 等等)
[ ] 增加 git 模式，针对当前改动的文件才转 AST 包裹，提取
[ ] 词条提取 cleanMode，目前如果代码中没有这个词条了，提取后的文件依然会有

其他

源码

https://github.com/wuqiang1985/i18n-helper

NPM 包

https://www.npmjs.com/package/i18n-helper-cli

目前还在完善中，欢迎大家试用，大家有问题可以提 issue。