前端国际化自动工具-国际化文案配置系统

背景

笔者之前所在的公司主要做东南亚以及欧洲一些国家的业务，做的是 Web 后台管理系统，项目被不同国家（有的项目多达七八个国家）的客户使用，所以前端项目需要支持多语言，也就是适配国际化。

日常编码中，系统需要接入前端 web 国际化插件，vue 项目使用的是 vue-i18n，而 react 项目使用 react-i18next，这些插件原理都是根据前端提供的一套语言包json文件（例如en-US.json，zh-CN.json）, 每份语言包都以key：value对象形式存储代码标记：实际渲染的语言文案一一对应的数据，然后插件根据用户的语言切换，替换展示不同的语言。

其中，语言包中 的 key 值可以是直接的中文文案：确定 或者是 类似 ：menu.dashboard.confirm 的字符串。通常情况下，如果业务没有特殊要求，为了方便业务代码的阅读，我们直接使用中文文案做为语言包的key值。

面临的问题

这里面多语言的切换展示都能由 i18n 插件帮我们处理，但是，有一个问题是比较麻烦的，那就是如何提取、收集、整理、翻译、录入这些文案，很多时候，这些都是手工完成。通常，在业务代码完成后，项目的文案key需要前端开发提取，整理，收集后，供翻译人员进行翻译，添加多国语言，然后经过校对和审核，再通过前端开发导入到项目代码中，此过程往往非常重复繁琐，存在工作效率低，又容易出错的问题。

刀耕火种

最开始，前端开发是写完需求业务代码，然后整理这次需求的页面上需要被翻译的文案，整理后放在谷歌文档excel表格上，然后呼叫翻译小组的小姐姐们进行翻译，待翻译结束，再经过审核校对，前端开发又手动录入到代码里，其过程极为繁琐，前端开发不只需要一个个找出文案，最后还得一个个录入到语言包json文件里，像我们有时候一个需求迭代里面有几百个文案，整理过程可谓又辛苦又无聊，过程大概如下图所示：

农业时代

后来，组里的同事终于受不了，利用xlsx.js撸了一个nodejs插件，在录入这一步上，不再手工一个个敲进去，而是通过插件将翻译好的文案excel数据转换生成新的语言包文件（zh-CN.json，en-US.json等等）。这样虽然简化了录入过程，但是还会面临以下几个问题：

• 系统分开语言包各个模块，每次需求都是用独立的语言包文件，这样，系统就会有多个语言包数据冗余。比如，每个页面都几乎有“确定”，“取消”这些文案，每次都需要重复录入，到了翻译阶段，翻译人员就需要多次翻译同一个文案

• 翻译、整理、校对、审核、的过程依赖于谷歌文档，每次需求都是新的文档，这样查找起来麻烦复杂
• 待翻译完成后，前端开发得登录文档下载excel文件，然后启动插件，生成json语言包
• 项目文案如果有临时修改，前端开发得登录谷歌文档对文案key进行修改，同时通知到翻译人员，待翻译人员同步修改后，再重新执行上面一步操作
• 系统的语言包文案key的提取还是得前端开发一个个敲进去，过程极度无聊，而且还会不小心打错字

工业时代

于是，针对上述的问题，是否可以开发出一个系统，能达到以下的工作效果呢？

• 提取文案自动化，无需前端开发手工录入
• 独立的公司内部文案配置系统，支持翻译人员在线录入文档，不依赖于谷歌文档
• 录入文案自动化，无需前端开发手动下载、移动到项目代码里面
• 录入文案时，能实时diff新旧语言包文件差异，让前端开发知道本次新增、修改，删除了多少文案
• 支持文案进行模块区分，比如需求a有文案xxx，xxxx，文案xxx隶属于需求a和需求b
• 支持excel、json格式语言的导入和导出
• 文案新增/修改/删除 有操作历史记录，可以随时查看某个文案什么时候被编辑过，翻译人员某个时候修改了哪个文案的内容

总而言之，就是希望有一套系统，能够把国际化这套流程工作通过程序自动完成，而作为前端开发，能够不处理或者少处理相关的工作，就像写国内的中文项目一样，直接写中文文案，系统自动处理国际化，达到无感知开发多语言国际化项目的目的

于是，便有了这套自动国际化文案配置系统。

自动国际化文案配置系统

架构

系统架构如图所示：

其中，文案解析器结构为

其系统运行流程是：

1. 翻译人员打开 自动国际化文案配置系统 前端页面
2. 每次系统前端页面进行刷新，页面会调用更新源代码接口,通知系统后台进行业务项目源代码的拉取和更新
3. 对应地，系统后台执行更新业务项目源代码，使用文案解析器对源代码进行解析，读取文案 key 的词条，收集、整理、去重后，同步到系统内置的数据库
4. 系统后台回传到系统前端页面
5. 翻译人员进行文案的翻译、修改、更新、删除等操作
6. 翻译人员完成翻译工作后，通知到前端开发
7. 前端开发使用辅助插件 @mango-scripts/i18n-scripts 进行一键下载、导入语言包到业务系统本地代码中

可以看到，这个过程，作为前端开发，无需参与其中文案的提取工作，从繁杂无聊的文案 key 的提取中解放出来，而最后的文案录入工作，也有辅助插件一键完成

那么，作为前端开发，只需要在业务项目的初期，部署接入该自动国际化文案配置系统，然后，在需求代码编写中，只需像写国内的中文项目一样，文案 key 使用中文，每次业务代码完成时，通知翻译人员进行文案翻译，待翻译工作结束后，执行项目辅助脚本，一键更新到本地项目里面

系统预览

以下是系统部分预览图

登录页面

管理员账号注册页面

系统注册默认邀请码：mango-i18n-system-invitation-code ,可用于管理员账户的注册，可在项目部署前，手动修改该环境变量来变更（文件地址：mango- i18n-system/packages/server/.env）

文案配置页面

添加翻译词条

操作记录页面

人员配置

解析配置

账户设置

系统特性

• 自动拉取业务项目源代码
• 自动提取业务项目代码中文文案 key 到系统中
• 支持使用辅助插件 @mango-scripts/i18n-scripts 进行一键下载、导入语言包到业务项目本地代码中
• 支持用户管理、操作记录 等常规后台管理系统功能，方便对文案变更作全流程跟踪
• 支持正则表达式、AST两种解析方式
• 支持vue，js，jsx，ts，tsx，svelte等多种格式文件
• 支持配置文案模块标识，配置无需提取的文案等功能
• 支持文案的 excel、json 等格式的上传以及下载
• 系统使用文件 hash 进行缓存，未修改过的业务代码文件不作解析，提高解析速度
• 部署方便，使用 docker 一键部署

系统技术栈

• 系统前后端全栈 采用 TypeScript 进行编写
• 文案解析器：@mango-scripts/i18n-utils：基于 babel, vue-template-compiler, hyntax, pug, svelte/compiler 等 对目标源码进行 AST 解析
• 辅助插件：@mango-scripts/i18n-scripts：基于 commander，fs-extra，glob，inquirer，undici 等
• 系统前端基于 react@17, react-router@6, redux，rematch, Antd, echarts, react-json-view 等
• 系统后台主要采用 nestjs 全家桶 以及 typeorm，execa， exceljs，glob，jsonwebtoken 等
• 数据库方案采用轻量级数据库 splite3
• 项目整体基于 docker，使用 docker-compose 一键部署

系统使用

只需要简单几步即可部署好系统

部署

1. 准备一台公司内部空闲的服务器，下载docker以及docker-compose，以及谷歌 zx 插件 zx

2. 在服务器上找一个空目录，例如：/home/app/i18n/ ，进入该目录，克隆该项目源码到目录里面

git clone https://github.com/AlbertLin0923/mango-i18n-system.git

1. 切换到该项目根目录上

cd /home/app/i18n/mango-i18n-system/

1. 在项目根目录执行zx ./scripts/adapt.mjs ,该文件会帮助你修改项目一些配置文件，以适配你的 系统部署端口

2. 执行 docker-compose up -d 进行 docker 一键部署

这时候打开服务器对应的项目端口，例如：http://host:port/user/login （ host 为内网服务器 IP 地址，port 为我们刚才设置的端口） 就可以看到项目已经启动

配置

此时,进入项目地址, 应该能看到项目已经部署好了

1. 登录 http://host:port/user/login 进行账户的注册或者登录

   系统注册默认邀请码：mango-i18n-system-invitation-code ,可用于管理员账户的注册，可在项目部署前，手动修改该环境变量来变更（文件地址：mango- i18n-system/packages/server/.env）

2. 登录后 进入 系统配置-人员配置 系统配置-界面配置 系统配置-解析配置 进行项目配置

业务系统接入

1. 如上文提到，编码过程需要以 中文 作为文案，具体使用可参考 该项目mango-i18n-system/packages/client 代码
2. 业务项目 下载脚本插件  pnpm add @mango-scripts/i18n-scripts -D，
3. 业务项目package.json里添加更新指令：

"scripts": {
  "updateLocale": "i18n-scripts updateLocale -f http://xxx:5003/api/locale/get_locale_map -o ./src/locales/common/ -l zh-CN en-US id-ID"
}

其中

-o 参数为 在业务项目里存储语言包的目录地址，例如：./src/locales/common/
-f 参数为 部署的服务器的地址和端口，例如：http://xxx:5003/api/locale/get_locale_map
-l 参数为 需要下载的语言包列表，例如：zh-CN en-US id-ID

1. 当需要更新语言包的时候，只需要执行pnpm run updateLocale即可

更多配置

配置文案模块标识

系统支持文案添加模块标识，可通过如下注释进行标识：

例如：在目标 src/views/xxx/index.vue文件最上面加注释：

<!-- translateModules:["需求2022009","需求2020102"] -->

或者，在 src/utils/request.ts文件最上面添加注释：

// translateModules:["需求2022009","需求2020102"]

系统会自动读取模块标识，该文件下的所有提取到的中文 key 文案，都将带有属性 modules:'需求2022009,需求2020102'，方便在系统前端上进行区分和筛选

配置无需提取的文案

系统会默认忽视业务代码里面的注释，但有些时候，我们一些未被注释的特殊的中文文案 key 并不想出现在自动文案配置系统前端页面上，这时候，我们可以在 AST 解析模式下，支持类似eslint-disable的注释效果，以注释不需要提取的中文文案 key

// 这种注释引擎会忽略整个文件中文文案key的提取，优先级最高
// translate-disable-entire-file

const getFilterStatusMap = (statusMap, type) => {
  if (type === 'pendingCase') {
    return statusMap.filter((i) => {
      return (
        // 这种注释引擎会忽略提取中间包裹的代码段中的中文文案key
        // translate-disable
        i.text === '待处理' ||
        i.text === '处理中'
        // translate-disable
      )
    })
  } else if (type === 'allCase') {
    return statusMap.filter((i) => {
      return (
        // 下面注释引擎会忽略提取 下一行 代码的中文文案key
        // translate-disable-next-line
        i.text === '已处理'
      )
    })
  } else if (type === 'myCase') {
    return statusMap.filter((i) => {
      return (
        // 下面注释引擎会忽略提取 当前行 代码的中文文案key
        i.text === '无需处理' || // translate-disable-line
      )
    })
  }  else {
    return statusMap
  }
}

源码

项目源码地址

• mango-i18n-system

TODO List

• 改善部署体验
• 文案解析器支持更多格式的文件

参考资料

Kiwi-国际化全流程解决方案

字节前端如何基于 AST 做国际化重构？

astexplorer