Nupital Pomp Mesmerises

    ext-intl
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.1 • Public • Published

    ext-intl

    基于TypeScript AST APIs配置国际化工具

    功能

    1. 提取指定目录下的所有中文词条,支持上传到远程词库平台(v3.0.0 及以上版本)

    2. 支持词条原处替换(可选)

    3. 按源目录结构生成多语言词条文件

    4. 集成kiwi-intl(可选)

    5. 可多次运行,增量提取(需要 v2.1.0 及以上版本)

    6. 和词库平台联动,自动填充非中文词条/词条翻译更新

    使用

    注意:若未使用多语言词库平台,请使用v2.1.x版本

    API 调用

    1. yarn add --dev ext-intl
    2. 新建xx.js
    const {
      sync,
      start,
      update,
      generateConfigFile,
      readConfigFile,
      checkConfig,
    } = require('ext-intl')
    const config = {...}
    // 生成配置文件
    generateConfigFile(true)
    // 读取配置文件
    readConfigFile()
    // 检测配置文件,如果存在,直接返回,否则将会在本地生成
    checkConfig({...initConfig})
      .then(conf => {
        console.log(conf)
      })
    // 同步远程词条数据
    sync(config.origin, config.accessKey)
    // 开启一次完成的提取
    start(config)
    // 进行一次本次词条更新
    update(config.langs[0])
    1. 项目根目录下运行node xx.js

    CLI 使用方式(强烈推荐)

    1. yarn add --dev ext-intl
    2. package.json中,scripts中配置如下:
      {
        ...
        "scripts": {
          ...
          "intl:config": "extintl config -o",
          "intl:sync": "extintl sync",
          "intl:start": "extintl start",
          "intl:update": "extintl update"
        }
      }
    1. 运行yarn intl:xx即可

    API

    /**
     * 同步远程词条并写入到本地
     * @param origin 远程地址
     * @param accessKey 配置的应用访问key
     * @returns
     */
    function sync(origin: string, accessKey: string): Promise<void>;
    
    /**
     * 开启一次完整的词条提取
     * @param config 配置
     * @returns
     */
    function start(config: ExtConfig): Promise<void>;
    
    /**
     * 更新本地已经维护好的词条信息
     * @param mainLangType 多语言环境下的主要语言(不需要翻译)
     */
    function update(mainLangType: string): Promise<void>;
    
    /**
     * 检查配置的流程:
     * 1. 如果传入了config,则直接使用config以及默认配置合并
     * 2. 如果没有传入config,则会寻找本地配置文件
     * 3. 如果本地配置文件不存在,则会询问是否使用默认配置生成配置文件
     * 4. 读取读取传入config或者配置文件config,合并后返回
     */
    function checkConfig(config: ExtCustomConfig): Promise<ExtConfig>;

    配置项

    参数 说明 类型
    outputPath(已废弃,兼容原因未删除) string
    rootPath 源文件或源文件目录 string
    extractOnly 是否只扫描文件,并不进行替换,如果设置为false,则会进行源文件替换,且集成kiwi-intl boolean
    whiteList 文件类型白名单,指定只扫描文件类型,可过滤掉图片/字体等文件的干扰 string[]
    prefix 在替换模式下,需要添加到源文件顶部的内容,一般为导出等 string[]
    templateString.funcName 处理模板字符串时,用于原处替换的函数名称 string
    fieldPrefix 生成字段命名时,使用的前前缀字符串,字段命名规则为{prefix}_{index},默认值:intl string
    versionName 当次运行的版本,内部自动维护,请不要手动传入,命名规则 v{index}|string
    origin 词库平台的 OpenAPI 地址(graphql 实现) string
    accessKey 词库平台应用的访问权限 key string
    langMapper 语言映射(key 作为当前多语言脚本语言,value 作词库平台支持语言)|Record<string, string>

    参数默认值如下:

    export const DEFAULT_CONFIG: IConfig = {
      outputPath: resolvePath('./i18n'),
      rootPath: resolvePath('./src'),
      langs: ['zh-CN', 'en-US'],
      extractOnly: true,
      whiteList: ['.ts', '.tsx', '.js', '.jsx'],
      prefix: [],
      templateString: {
        funcName: 'kiwiIntl.get',
      },
      fieldPrefix: 'intl',
      origin: '',
      accessKey: '',
      langMapper: {
        'zh-CN': 'zh-CN',
        'en-US': 'en-US',
      },
    }

    一般使用步骤

    首次运行

    1. 运行yarn intl:config生成配置文件,并修改
    2. 运行yarn intl:start 并在extractOnly: true模式下提取中文词条,提取完成后,根据提示上传至词库平台
    3. 在词库平台上维护相关词条,维护完成后,再次运行yarn intl:start进行一次完整的提取,至此,多语言提取和替换工作完毕
    4. 和首次运行类似,增量提取可以不用执行步骤1生成配置文件

    更新多语言词条翻译

    1. 在词库平台上完成对词条多语言的更新维护(请注意不要修改词条 key)
    2. 运行yarn intl:update同步词条到本地,并进行词条翻译的更新

    已知问题

    ⚠️ 推荐使用extractOnly模式,只生成多语言文件,不修改源代码;如果使用一键替换源代码,即extractOnly=false,请做好版本管理,以免造成不可逆的丢失。

    1. 不支持某些复杂模板字符串的提取
    2. 部分代码格式化异常(需要额外的格式化)

    ChangeLog

    查看更新日志

    Install

    npm i ext-intl

    DownloadsWeekly Downloads

    50

    Version

    3.1.1

    License

    MIT

    Unpacked Size

    63.8 kB

    Total Files

    54

    Last publish

    Collaborators

    • limoer