一个命令搞定 Web 国际化

一个命令搞定 Web 国际化

投稿备用

背景

随着出海的业务越来越多,web 应用面临越来越多的国际化的工作。如何高效,高质量的完成 Web 前端国际化工作,已经是摆在 web 前端同学的急需解决的问题。

i18n-helper-cli 是什么

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

为什么需要 i18n-helper-cli

Web 国际化流程

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

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

问题

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

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

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

解决方案

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

原理

整体方案

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

包裹词条方案详解

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

  1. 找到你好
  2. 替换成t('你好')

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

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

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

方案 1 – 正则

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

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

方案 2 – AST

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

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

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

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

  1. Parse阶段:词法分析 & 语法分析
  2. Transform阶段:生成AST,抽象语法树
  3. 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,prettierwebpack等等都是通过对源码进行分析,转换,生成实现各种各样的功能。

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

  1. 上面说的代码转 AST 时的各种类型,我们怎么知道转成什么类型了呢?

答:https://astexplorer.net/
image.png

  1. 另外这些类型如何构造新的节点?

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

image.png

如何使用 i18n-helper-cli

实例

请参考 example

安装

注意:请确保 Nodejs 版本大于 14!!!

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

快捷使用

  1. 在项目根目录下生成 i18n.config.json 文件
# 交互式命令行
i18n-helper init
# 生成默认配置文件,具体参见【配置说明】( 推荐大家用这个哈,交互方式的的后面加了不少配置海内来得及补齐)
i18n-helper init -y
  1. 包裹 & 提取 & 翻译 & 统计
# 包裹 & 提取 & 翻译 & 统计 i18n.config.json 中 srcPath 文件中的中文词条
i18n-helper scan -wetc
  1. 切换 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。

本文来自开发者投稿,不代表腾讯云立场,转载请注明出处:https://computeinit.com/archives/5393

发表评论

登录后才能评论
交流群