@oceanbase-odc/ob-intl-cli

什么是ob-intl-cli

ob-intl-cli(以下简称oic)是一个前端项目国际化工具，诞生于ODC开源过程中。 用于在开源过程中逐步替代在原有的国际化流程中所使用到的内部国际化框架 @ali/parrot-tool-must（以下简称must），oic所使用的配置文件与must基本保持一致，项目中原有的关于must的配置脚本，只需进行少量修改即可使用oic替代must进行项目的国际化。 如果你对前端国际化的实现流程不太熟悉的话，通过阅读该文档尾部关于前端国际化相关实现流程的介绍，你会对该流程有一个大概的认知。

一、 ob-intl-cli有哪些不足/不支持的功能

• oic目前只支持(ts|js|tsx|jsx)等文件类型，因为ODC前端团队这边基本都是用的React，所以目前没有支持vue或者其他类型的想法。
• oic目前不支持must中的hook功能，可能将在未来的某个版本中引用类似于webpack的hook系统。

二、 ob-intl-cli目前支持的功能

• 文案提取
• 冗余文案清理
• 重复文案收集替换
• 依赖智能引入收集
• 支持旧版本产物迁移

三、 oic目前支持的配置项

以下是示例配置项

const pkg = require('../package.json');
const path = require('path');

module.exports = {
  name: '@oceanbase-odc/ob-intl-cli',
  entry: path.resolve(process.cwd(), './src/examples/react-demo/src'),
  output: path.resolve(process.cwd(), './src/examples/react-demo/src/locales'),
  sourceLang: 'zh-CN', // 默认简体中文
  targetLang: 'en-US', // 默认英语，后面会支持多目标语言。
  clearLangs: ['zh-CN', 'en-US'],
  sep: '.',
  mergeBaseFile: true,
  exclude: (path) => {
    return (
      path.includes('src/.umi')
      || path.includes('src/locale')
      || path.includes('src/main')
      || path.includes('package.json')
    ); // 不处理 .umi 下的文件
  },
  matchFunc: matchText,
  injectContent: {
    import: "import { formatMessage } from '@umijs/max';\n",
    method: `formatMessage({id: '$key$' })`,
    withDefaultMessage: true,
    defaultMessageKey: 'defaultMessage',
  },
  migrateConfig: {
    defaultMessage: true,
    parametersShortHand: true,
  },
}

1. name: string;

配置此项，将会额外添加信息在GenerateKey生成的key的首部，通常是package.json中的name，默认为空。

2. entry: string;

oic 执行的根目录。

3. output: string;

oic 执行完成后输出产物的目标路径

4. sourceLang: string;

Translate过程翻译文案的源语言，默认源语言为简体中文，既zh-CN;

5. targetLang: string;

Translate过程翻译文案的目标语言，默认目标语言为英语，既en;

6.clearLangs?: string[];

Clear过程要清理的已经停止使用的废弃文案，配置为['zh-CN', 'en-US', 'zh-TW']时会自动清理项目中简体中文、美式英文、繁体中文的文案文件中的废弃内容。

7. sep: string;

配置此项，将会修改GenerateKey过程中生成的key所使用的路径分隔符，默认使用.。

8. mergeBaseFile: boolean;

配置此项，将会影响在oic输出产物时执行的策略，为true时将合并原有文件，为false时则不合并。

9. exclude: string | string[] | function(originPath: string): boolean;

设置哪些文件或文件夹的源代码是不需要进行国际化处理的，支持多种形式。

// 1. exclude: string; 
// 例如'src/.umi'，oic在执行过程中会自动跳过'src/.umi'底下的源代码。

// 2. exclude: string[];
// 例如 ['src/.umi', 'src/locale']，oic在执行过程中会跳过'src/.umi'及 'src/locale'底下的源代码。

// 3. exclude: function (originPath: string); 
// 例如
// oic在执行过程中会跳过满足excludeFunction的文件路径下的源代码。
function excludeFunction (originPath) { 
  return originPath.includes('src/.umi');
};

10. matchFunc: function(code: string; nodePath?: NodePath;): boolean;

Extract过程中提取文案所使用的筛选函数，默认提取简体中文。

const includeChinese = (code, nodePath) => {
  return new RegExp('[\u{4E00}-\u{9FFF}]', 'g').test(code);
}

11. injectContent

Transfrom过程中注入到代码文件中的内容配置参数。

import

Extract 过程中被提取替换后的文件需要注入的代码片段，必填项。

method

Extract 过程中被提取替换文案的国际化功能函数形式，必填项。

withDefaultMessage

Extract 过程中被提取替换文案的国际化功能函数是否需要携带默认文案，可用于兜底显示文案内容，可选项。

defaultMessageKey

可选项当用户配置withDefaultMessage为true时，可以选择设置该项的key值，默认为defaultMessage.

12. migrateConfig

Migrate所使用的配置参数。

defaultMessage

是否在迁移过程中为旧版本产物添加defaultMessage, 内容以中文文案内容为准。选填项。

// before migrate
formatMessage({ id: 'src.pages.Create.DataArchive.Create.488A69D6',});
// after migrate
formatMessage({ id: 'src.pages.Create.DataArchive.Create.488A69D6', defaultMessage: 'XXXXXXX'});

parametersShortHand

是否在迁移过程中为旧版本产物中formatMessage中使用到的参数开启shortHand语法。选填项。

// before migrate
formatMessage({ id: ".Users.ccj.work.ob-intl-cli.src.examples.react-demo.src.pages.ODC.1E85598D" }, { count: count });
// after migrate
formatMessage({ id: ".Users.ccj.work.ob-intl-cli.src.examples.react-demo.src.pages.ODC.1E85598D" }, { count });

四、 使用ob-intl-cli的过程中

• 可以在代码首部使用 // @oic-file-ignore 来提示oic跳过该文件。
• 可以在代码首部使用 // @oic-line-ignore 来提示oic跳过下一个表达式中的文案。

五、 对于前端项目国际化，前端开发者需要了解的知识点

babel插件/库对源代码进行处理的大致流程

• 使用babel.parse解析源文件中的源码后，我们会得到一棵抽象语法树(Abstract syntax tree， 既AST)，既下图中的Parse过程;
• 通常一些babel插件或者工具会通过@babel/traverse来遍历AST上的每个节点，对节点进行若干处理后，你会将原有的AST改造成一棵新的AST，既下图中的Transform过程;
• 将经Transform过程生成的新的AST交由@babel/generator处理，假如Transform过程中你的操作是合理且正确的，你将在Generate过程后得到一份被改造过的代码;

前端项目国际化是如何实现的？

而oic也是基于以上流程实现的前端国际化。 我们在Transform的过程中会进行目标文案的提取收集(Extract)、批量翻译(Translate)生成语义性和辨识性较高的key(GenerateKey)、对原有的AST进行用户的配置注入和改造(Inject)。 最后用Generate过程后生成的代码替代源文件中的代码，通常在完成以上步骤之后，我们还会对代码进行一定程度的代码美化工作，既Prettier。

注：此图来自网络文章[Revealing the magic of AST by writing babel plugins]:https://dev.to/viveknayyar/revealing-the-magic-of-ast-by-writing-babel-plugins-1h01