@recurve/i18n_tools

A tool for synchronizing i18n files between Feishu (Lark) Wiki and local projects.

Install

  # npm
  npm install -D @recurve/i18n_tools
  # pnpm
  pnpm add -D @recurve/i18n_tools

  # Global installation
  npm install -g @recurve/i18n_tools
  pnpm install -g @recurve/i18n_tools

Usage

Config

Feishu (Lark)

Currently, only synchronization of I18N files in Wiki is supported. You need to create an I18N document directory containing module names in English, as follows:

// There are two modes. If modulesPath is not configured, the fileName directory (default is i18n) will be generated in the root directory, with modules contained within it
  --i18n
    --rearc
    --ruleset
// If modulesPath exists, the fileName directory (default is i18n) will be generated in the corresponding module directory under the modulesPath directory
  --modulesPath
    --rearc
      --i18n
    --ruleset
      --i18n

Then, create translation module tables in the corresponding spreadsheets, as follows:

  --rearc
    route
    page
    page-tip
    error-customer
    error-status
    error-code
  --ruleset
    route
    page
    page-tip

When synchronizing i18n content from remote Feishu tables, the local file directory structure will be generated according to the directory structure. Table names, separated by -, will generate corresponding directory names, as follows:

  page and page-tip ==>
  # Generate page directory and related files
  --page
    {locale}.{ext}
    index.{ext}
    --tip
      {locale}.{ext}
      index.{ext}
  # Content will be
  export default {
    key: value
  }
  # If it's a JSON file, it won't include export default

Additionally, the related modules of rootModule will be automatically exported to the root directory specified in the configuration file, while others will generate corresponding directories and export related files in their own directories. The final file structure will be as follows:

i18n
  --rootModule
    --route
      {locale}.{ext}
      index.{ext}
    index.{ext}
  --otherModules
    --route
      {locale}.{ext}
      index.{ext}
    index.ext
  index.ext

Also, since module names may contain special characters that are not allowed as import identifiers in code, these names will be automatically processed as follows:

  data-collect
    -> import datacollect from "xxxx"
  123data
    -> import _123data from "xxxx"

Project Configuration

Create a .syncI18n.mjs configuration file in the project root directory (currently only JavaScript module format is supported):

export default {
  "appId": "xxxxx",
  "appSecret": "xxxxxxx",
  "spaceId": "xxxxxx",
  "wikiDocToken": "xxxxxx",
  "i18nExt": "json",
  "indexExt": "ts",
  "fields": ["error", "page", "route"],
  "fileName": "i18n",
  "root": "./src",
  "modulesPath": "./apps", // Default is empty
  "excludeModules": [], // Modules to exclude, default is empty
  "langs": ["en", "zh-CN"],
  "needFilter": {
    "ruleset": []
  },
  "rootModule": "rootName",
  "titleSplit": "-",
}

• appId: Feishu application ID. This tool requires Feishu bot support, and the bot needs to have read/write permissions for the corresponding wiki.

• appSecret: Feishu application SECRET.

• spaceId: Wiki space ID.

• wikiDocToken: Token for the i18n file directory.

  • For example, in https://xxxxx.feishu.cn/wiki/xxxxxx, it's the content after wiki/: xxxxxx.

• i18nExt: Extension for generated i18n files.

• indexExt: Extension for generated index files.

• fields: Effective fields that will match table names containing fields in the array. Tables not in the array will not be synchronized.

  • Note that for names separated by -, the part before - is used as the basis. For example, page applies to both page and page-tip.
  • Default value: ["error", "page", "route"]

• fileName: Name of the i18n folder.

• root: Root directory.

• modulesPath: Module directory, default is empty. If it has a value, it will look for the corresponding module folder in this directory and generate the corresponding i18n directory under the module.

• excludeModules: Modules to exclude, default is empty. If it has a value, this module will be ignored. For example, excludeModules: ["ruleset"] will not synchronize i18n content in the ruleset module.

• langs: Matching languages.

  • Default value: ["en", "zh-CN"]

• needFilter: Tables that need filtering. Only rows containing 1 in the specified tables will be downloaded. For example, only page and page-tip in the ruleset module will be filtered:

  "needFilter": {
      "ruleset": ["page", "page-tip"]
    },

• rootModule: Used to identify the root module. The root module's tables will have some common translations (e.g., error). The content of the root module will not be placed in a separate folder but directly under i18n, and a common index.ts file will be generated.

  • No default value, required.

• titleSplit: Considering that Feishu documents may not be directly named after the module, a separator configuration is provided. It will take the string after the first separator as the actual module name. If not provided, the complete document name will be used as the module name.

  • Default value: ''

Commands

• pull: Synchronize i18n files from the specified directory in Feishu documents to local. Note that this uses complete overwrite mode.

  • --modules [moduleName]: Only synchronize i18n for the specified module.

• push: Synchronize local i18n files to the specified directory in Feishu documents. Note that this uses complete overwrite mode.

  • --modules [moduleName]: Only synchronize i18n for the specified module.
  • --sheets [sheetName]: Only synchronize i18n for the specified table. You can use the moduleName:sheetName format to specify a specific table under a specific module.