i18n-easy 1.0.0

package/README.md

@@ -0,0 +1,527 @@
+# i18n-easy
+
+## 介绍
+
+- 一键替换中文字符为国际化书写方式，适用于 `vue2/vue3/react`；
+- 支持文件类型：`vue/js/ts/jsx/tsx`；
+
+## 配置
+
+- `js` 配置适用于`js/ts`文件，`jsx` 配置适用于` jsx/tsx` 文件；
+- 相关`ts`类型；
+
+  ```typescript
+  // 语言配置
+  interface LangType {
+    name: string // 目标翻译语言
+    i18nFilePath: string // 语言文件地址
+  }
+
+  // vue中国际化配置
+  interface I18nInfoType {
+    template?: {
+      // vue模版中配置
+      callMethodName: string // 国际化调用方法m
+    }
+    script?: {
+      // vue选项式api脚本中配置
+      callMethodName: string // 国际化调用方法
+      injectImport?: string // 注入导入语句代码
+      injectCodeToTopLevel?: string // 注入到顶部的代码
+    }
+    scriptSetup?: {
+      // vue组合式api脚本中配置
+      callMethodName: string // 国际化调用方法
+      injectImport?: string // 注入导入语句代码
+      injectHooksCall?: string // 注入的hooks调用代码
+      injectCodeToTopLevel?: string // 注入到顶部的代码
+    }
+    js?: {
+      // vue框架中js、ts文件配置
+      callMethodName: string // 国际化调用方法
+      injectImport?: string // 注入导入语句代码
+      injectCodeToTopLevel?: string // 注入到顶部的代码
+    }
+    jsx?: {
+      // vue框架中使用jsx、tsx文件配置
+      callMethodName: string // 国际化调用方法
+      injectImport?: string // 注入导入语句代码
+      injectCodeToTopLevel?: string // 注入到顶部的代码
+    }
+  }
+
+  // react中国际化配置
+  interface ReactI18nInfoType {
+    js?: {
+      // js、ts文件中配置
+      callMethodName: string // 国际化调用方法
+      injectImport?: string // 注入导入语句代码
+      injectCodeToTopLevel?: string // 注入到顶部的代码
+    }
+    jsx?: {
+      // jsx、tsx文件中配置
+      callMethodName: string // 国际化调用方法
+      injectImport?: string // 注入导入语句代码
+      injectHooksCall?: string // 注入的hooks调用代码
+      injectCodeToTopLevel?: string // 注入到顶部的代码
+    }
+  }
+
+  // jsxText节点
+  interface JSXText extends ESTree.BaseNode, ESTree.BaseExpression {
+    type: 'JSXText'
+    value: string
+    raw: string | undefined
+  }
+
+  //  vue中文本节点
+  type TextNode = AST.VText | AST.VAttribute | ESTree.TemplateLiteral | (ESTree.Literal & Rule.NodeParentExtension) | JSXText
+
+  //  react中文本节点
+  type ReactTextNode = ESTree.TemplateLiteral | (ESTree.Literal & Rule.NodeParentExtension) | JSXText
+
+  // 项目框架类型
+  type Framework = 'vue' | 'react'
+
+  // 配置文件生成对象键类型
+  type KeyType = 'hash' | 'pinyin' | 'pinyinWithNumber'
+
+  // fileToI18n方法options配置类型
+  interface FileToI18nConfig<T extends Framework> {
+    type: T // 框架类型
+    keyType?: KeyType // 生成的国际化文件key类型 默认为pinyin
+    i18nInfo: T extends 'vue' ? I18nInfoType : ReactI18nInfoType // 国际化配置信息
+    customIgnore?: (node: T extends 'vue' ? TextNode : ReactCollectItemType['textNode'], context: Rule.RuleContext) => boolean // 自定义判断节点是否忽略
+  }
+
+  // fileToI18nAndTranslate方法options配置类型
+  interface FileToI18nAndTranslateConfig<T extends Framework> extends FileToI18nConfig<T> {
+    lang: string[] // 目标语言列表
+    apiKey: string // 翻译API key
+  }
+
+  // 完整配置类型
+  interface Config<T extends Framework> {
+    projects: {
+      projectPath: string // 项目路径
+      lang: LangType[] // 语言配置
+      i18nInfo: T extends 'vue' ? I18nInfoType : ReactI18nInfoType // 国际化信息配置
+      keyType: KeyType // 生成的国际化文件key类型
+      type: T // 项目框架类型
+      customIgnore?: (node: T extends 'vue' ? TextNode : ReactTextNode, context: Rule.RuleContext) => boolean // 自定义是否忽略节点的国际化处理 true不处理 false处理
+    }[] // 项目配置
+    apiKey: string // 翻译API key
+  }
+  ```
+
+- `js`：配置项用于`js` 文件、`ts`文件；
+- `jsx`：配置项用于`jsx` 文件、`tsx`文件；
+- `template`：`vue`中`template` 模块；
+- `script`：`vue选项式api`中`script`模块；
+- `scriptSetup`：`vue组合式api`中`script`模块；
+
+## 使用说明
+
+1. 安装`i18n-easy`，`npm install i18n-easy`；
+
+2. 在项目根目录下新建`i18n_easy.js/i18n_easy.ts文件`；
+
+3. 在文件中配置转换规则，插件中导出了`defineConfig方法`，推荐使用`defineConfig`进行配置，例如：
+
+   ```typescript
+   import { defineConfig } from 'i18n-easy'
+
+   export default defineConfig({
+     projects: [
+       {
+         projectPath: './',
+         lang: [
+           {
+             name: 'en',
+             i18nFilePath: './lang/english.json',
+           },
+           {
+             name: 'zh',
+             i18nFilePath: './lang/chinese.json',
+           },
+         ],
+         i18nInfo: {
+           template: {
+             callMethodName: '$t',
+           },
+           script: {
+             callMethodName: 'this.$t',
+           },
+           scriptSetup: {
+             callMethodName: '$t',
+             injectImport: "import useI18n from 'vue-i18n'",
+             injectHooksCall: 'const { t: $t } = useI18n()',
+           },
+           js: {
+             callMethodName: 'i18n.t',
+             injectImport: "import i18n from '@/i18n/i18n.js'",
+           },
+           jsx: {
+             callMethodName: 'vm.$t',
+           },
+         },
+         keyType: 'pinyinWithNumber',
+         type: 'vue',
+       },
+     ],
+     apiKey: '',
+   })
+   ```
+
+4. 将待替换的文件放入`git`暂存区（`git add`区域，只会替换`git`暂存区中的文件，并且替换**文件最新内容**）；
+
+5. 在终端执行`npx i18n-easy`命令（需在项目根目录下执行，在处理文件路径时，会以项目根目录为基准）；
+
+## I18nEasy类
+
+`i18n-easy`包提供了`I18nEasy`类的导出，可供用户自行调用；
+
+1. 导入方法：
+   - `esm`模块：`import { I18nEasy } from 'i18n-easy';`
+   - `commonjs`模块：`const { I18nEasy } = require('i18n-easy');`
+
+2. 类`I18nEasy`中提供了部分方法：
+   - `transformModifiedFiles`：获取`git`暂存区文件进行国际化转换、翻译，并更新语言文件（命令`npx i18n-easy`底层也是调用此方法）；注意：使用此方法将读取配置``i18n_easy.js/i18n_easy.ts`信息；
+     - 参数：无
+     - 返回值：无
+
+     ```typescript
+     import { I18nEasy } from 'i18n-easy // 导入I18nEasy类
+
+     const i18nEasy = new I18nEasy()
+     // 调用transformModifiedFiles方法（将使用配置文件i18n_easy.js/i18n_easy.ts配置信息）
+     i18nEasy.transformModifiedFiles().then()
+     ```
+
+   - `fileToI18n`：将指定文件转换成国际化写法（不进行翻译），并返回处理结果；
+     - 参数：
+       - `filePath`：文件绝对路径；
+       - `options`：配置项信息，具体可见配置相关ts类型中[`FileToI18nConfig`类型](#配置)；
+     - 返回`Promise`：
+       - `oldFileContent`：转换前的文件内容；
+       - `newFileContent`: 转换后的文件内容；
+       - `fixed`：是否进行转换；
+       - `filePath`: 文件路径；
+       - `keyValueMap`：文件中的转换字段；
+
+     ```typescript
+     import { I18nEasy } from 'i18n-easy
+
+     const i18nEasy = new I18nEasy()
+
+     const filePath = '/Users/code/1.js' // 文件绝对路径
+     const config = { // 配置项
+       type: 'vue',
+       keyType: 'pinyinWithNumber',
+       i18nInfo: {
+         js: {
+           callMethodName: "i18n.t",
+           injectImport: "import i18n from '@/i18n/i18n.js'",
+         },
+     	}
+     }
+
+     i18nEasy.fileToI18n(filePath, config).then()
+     ```
+
+   - `fileToI18nAndTranslate`：将指定文件转换成国际化写法并进行翻译，并返回处理结果；
+     - 参数：
+       - `filePath`：文件绝对路径；
+       - `options`：配置项信息，具体可见相关ts类型中[`FileToI18nAndTranslateConfig`类型](#配置)；
+     - 返回`Promise`：
+       - `oldFileContent`：转换前的文件内容；
+       - `newFileContent`: 转换后的文件内容；
+       - `fixed`：是否进行转换；
+       - `filePath`: 文件路径；
+       - `keyValueMap`：文件中的转换字段；
+       - `translateResult`：翻译后的语言字段
+
+     ```typescript
+     import { I18nEasy } from 'i18n-easy
+
+     const i18nEasy = new I18nEasy()
+
+     const filePath = '/Users/code/1.js' // 文件绝对路径
+     const config = { // 配置项
+       type: 'vue',
+       keyType: 'pinyinWithNumber',
+       i18nInfo: {
+         js: {
+           callMethodName: "i18n.t",
+           injectImport: "import i18n from '@/i18n/i18n.js'",
+         },
+     	},
+       apiKey: '微软翻译apikey',
+       lang: ['en', 'zh'],
+     }
+
+     i18nEasy.fileToI18nAndTranslate(filePath, config).then()
+     ```
+
+   - `fileToI18nAndTranslateBatch`：将指定文件列表批量转换成国际化写法并进行翻译，并返回处理结果：
+     - 参数：
+       - `filePaths`：文件绝对路径数组；
+       - `options`：配置项信息，具体可见相关ts类型中[`FileToI18nAndTranslateConfig`类型](#配置)；
+     - 返回`Promise`：
+       - `transformResult`：转换结果数组；
+         - `oldFileContent`：转换前的文件内容；
+         - `newFileContent`: 转换后的文件内容；
+         - `fixed`：是否进行转换；
+         - `filePath`: 文件路径；
+         - `keyValueMap`：文件中的转换字段；
+       - `translateResult`：翻译后的语言字段；
+
+     ```typescript
+     import { I18nEasy } from 'i18n-easy
+
+     const i18nEasy = new I18nEasy()
+
+     const filePaths = ['/Users/code/1.js'] // 文件绝对路径
+     const config = { // 配置项
+       type: 'vue',
+       keyType: 'pinyinWithNumber',
+       i18nInfo: {
+         js: {
+           callMethodName: "i18n.t",
+           injectImport: "import i18n from '@/i18n/i18n.js'",
+         },
+     	},
+       apiKey: '微软翻译apikey',
+       lang: ['en', 'zh'],
+     }
+
+     i18nEasy.fileToI18nAndTranslateBatch(filePaths, config).then()
+     ```
+
+## 注意事项
+
+1. 当在 `vue` 文件中使用 `script` 标签的`src`属性引入**外部js、ts**时，需保证对应引入文件与**当前vue文件在同一目录下**。否则将以**js、ts配置**进行替换以及代码注入；
+
+2. 当在 `vue` 文件中使用 `script` 标签的`src`属性引入**外部js、ts**时，**对应js、ts文件**最好使用类型`export default {}` 或者 `export default defineComponent({})`的形式，否则将以 `script` 配置进行替换以及代码注入，而无法判断是否采用`scriptSetup`配置；
+
+3. 当函数参数为中文时会进行国际化替换，如需不进行替换，可使用注释`// @i18n-ignore`，例如:
+
+   ```typescript
+   // @i18n-ignore
+   fn(`不会被替换`) // 中文不会被替换
+
+   /* @i18n-ignore */
+   fn(`不会被替换`) // 中文不会被替换
+   ```
+
+4. 如需自定义是否替换指定节点可以通过配置函数`customIgnore`来实现，例如：
+
+   ```typescript
+   import { defineConfig } from 'i18n-easy'
+
+   export default defineConfig({
+     projects: [
+       {
+         projectPath: './',
+         lang: [
+           {
+             name: 'en',
+             i18nFilePath: './lang/english.json',
+           },
+         ],
+         i18nInfo: {
+           js: {
+             callMethodName: 'i18n.t',
+             injectImport: "import i18n from '@/i18n/i18n.js'",
+           },
+         },
+         keyType: 'pinyinWithNumber',
+         type: 'vue',
+         /**
+          * 自定义是否忽略节点的国际化处理 返回true不处理 false处理
+          * node为将要替换的节点（具体类型查看配置部分）
+          * context为eslint规则上下文（具体类型方法可查看eslint官方文档）
+          */
+         customIgnore: (node, context) => {
+           return node.type === 'JSXText'
+         },
+       },
+     ],
+     apiKey: '',
+   })
+   ```
+
+5. `vue`框架中支持使用`jsx`写法，但存在以下限制：
+   - 对于文件后缀名为`vue`但使用`jsx`写法的文件将根据是否使用`组合式api`而应用`script`或`scriptSetup`配置，例如：
+
+     ```vue
+     // test.vue（选项式api使用script配置）
+     <script lang="jsx">
+     export default {
+       data() {
+         return {
+           str: '中文',
+         }
+       },
+       methods: {
+         handleClick() {},
+       },
+       render() {
+         return (
+           <>
+             <div>中文</div>
+           </>
+         )
+       },
+     }
+     </script>
+
+     // test.vue（组合式api使用scriptSetup配置）
+     <script lang="jsx">
+     export default defineComponent({
+       setup() {
+         const str = '中文'
+         function handleClick() {}
+         return () => (
+           <>
+             <div>中文</div>
+           </>
+         )
+       },
+     })
+     </script>
+     ```
+
+   - 对于文件后缀名为`jsx`但使用`组合式api`将应`scriptSetup`配置（因为仍使用`setup`来实现组件），例如：
+
+      ```jsx
+      // test.jsx（组合式api将采用scriptSetup配置）
+      export default defineComponent({
+        setup() {
+          const str = '中文';
+          function handleClick() {}
+          return () => (
+            <>
+              <div>中文</div>
+            </>
+          );
+        },
+      });
+
+      // test.jsx（组合式api将采用scriptSetup配置）
+      export default {
+        setup() {
+          const str = '中文';
+          function handleClick() {}
+          return () => (
+            <>
+              <div>中文</div>
+            </>
+          );
+        },
+      };
+      ```
+
+6. `npx i18n-easy`会替换 git **暂存区**中文件的**最新内容**，例如：当前暂存区存在文件`test.js`，又修改`test.js`文件内容后，此时暂存区和更改区均存在`test.js`文件，但是更改区的`test.js`文件内容才是最新的，进行`cli`国际化替换操作将对文件最新内容进行替换；
+
+7. 对于`vue`框架，仅支持`vue、js、jsx、ts、tsx`文件，对于`react`框架；仅支持`js、jsx、ts、tsx`文件，其他文件类型将被忽略；
+
+8. 由于使用`cli`国际化操作会根据项目对文件进行分组，因此不在配置文件的项目路径下的文件，也将被忽略，例如：
+
+   ```js
+   import { defineConfig } from 'i18n-easy'
+
+   export default defineConfig({
+     projects: [
+       {
+         projectPath: './yourProjectPath', // 项目地址
+         lang: [
+           {
+             name: 'en',
+             i18nFilePath: './lang/english.json',
+           },
+         ],
+         i18nInfo: {
+           js: {
+             callMethodName: 'i18n.t',
+             injectImport: "import i18n from '@/i18n/i18n.js'",
+           },
+         },
+         keyType: 'pinyinWithNumber',
+         type: 'vue',
+       },
+     ],
+     apiKey: '',
+   })
+   ```
+
+   - 此时配置项目路径为`./yourProjectPath`，在处理过程中会过滤掉不在`./yourProjectPath`路径下的后代文件；
+
+9. 国际化语言文件仅支持`js、ts、json`文件格式，并且推荐使用以下任意格式，否则可能会出现语言文件内容解析失败问题；
+
+   ```js
+   // 1. en.js（ts同理）
+   module.exports = {
+   	// 键值对
+   }
+
+   // 2. en.js（ts同理）
+   export default {
+    // 键值对
+   }
+
+
+   // 3. en.json
+   {
+    // 键值对
+   }
+
+
+   // en.js (会替换失败)
+   const obj = {
+   // 键值对
+   }
+
+   export default obj
+   ```
+
+10. 对于转换模版字符串，变量将以对象的形式作为国际化调用方法的参数，并且对象`key`为`arg1～arg9`例如：
+
+    ```js
+    // 原始代码
+    const a = `你好${1 * 1}${1 + 1}`
+
+    // 转换后代码（例如调用方法为$t）
+    const a = $t('ni_hao_arg1_arg2', { arg1: 1 * 1, arg2: 1 + 1 })
+
+    // 语言字段
+    {
+      ni_hao_arg1_arg2: '你好{arg1}{arg2}'
+    }
+    ```
+
+11. 对于配置文件中的调用方法，例如：`$t`，在转换时会将键值作为第一个参数，参数对象作为第二个参数，例如：
+
+    ```jsx
+    // 原始代码
+    const a = `你好${1 * 1}${1 + 1}`
+
+    // 转换后代码（例如调用方法为$t）
+    const a = $t('ni_hao_arg1_arg2', { arg1: 1 * 1, arg2: 1 + 1 })
+
+    // 当使用国际化工具不支持这种传参时，可以对调用方法进行二次调用，例如：
+    import { useIntl } from 'umi'
+
+    // 自定义hooks，配置文件中使用customizeFormatMessage作为调用名称
+    function useCustomizeI18n() {
+      const { formatMessage } = useIntl()
+
+      function customizeFormatMessage(key, params) {
+        return params ? formatMessage({ id: key }, params) : formatMessage({ id: key })
+      }
+
+      return {
+        customizeFormatMessage,
+      }
+    }
+    ```

package/esm/assets/const.js

@@ -0,0 +1,7 @@
+// src/assets/const.ts
+var configFileNames = ["i18n_easy.mjs", "i18n_easy.cjs", "i18n_easy.js", "i18n_easy.ts", "i18n_easy.json"];
+var checkReg = /(module\.exports\s*=\s*|export\s*default\s*)?({[\s\S]*})/;
+export {
+  checkReg,
+  configFileNames
+};

package/esm/ast_transformer.d.ts

@@ -0,0 +1,19 @@
+import { Framework, SupportFileMap, I18nInfoType, ReactI18nInfoType, TextNode, ReactCollectItemType } from './type.js';
+import { type Rule } from 'eslint';
+interface Props<T extends Framework> {
+    fileContent: string;
+    fileName: string;
+    fileType: SupportFileMap[T];
+    type: T;
+    i18nInfo: T extends 'vue' ? I18nInfoType : ReactI18nInfoType;
+    customIgnore?: (node: T extends 'vue' ? TextNode : ReactCollectItemType['textNode'], context: Rule.RuleContext) => boolean;
+}
+export declare class AstTransformer {
+    private linter;
+    constructor();
+    convertFileContent<T extends Framework>(props: Props<T>): {
+        newFileContent: string;
+        fixed: boolean;
+    };
+}
+export {};

package/esm/ast_transformer.js

@@ -0,0 +1,54 @@
+// src/ast_transformer.ts
+import { Linter } from "eslint";
+import i18nEasyVue from "./eslint/vue/i18n_easy_plugin.js";
+import i18nEasyReact from "./eslint/react/i18n_easy_plugin.js";
+import * as vueParser from "vue-eslint-parser";
+import * as espree from "espree";
+import tsParser from "@typescript-eslint/parser";
+var AstTransformer = class {
+  linter;
+  constructor() {
+    this.linter = new Linter();
+  }
+  // 转换文件内容
+  convertFileContent(props) {
+    const { fileContent, fileType, fileName, i18nInfo, type, customIgnore } = props;
+    const settings = { i18nInfo, fileType, customIgnore };
+    const parserOptions = {
+      ecmaFeatures: { jsx: true },
+      parser: { js: espree, jsx: espree, ts: tsParser, tsx: tsParser }
+    };
+    const vueConfig = {
+      files: ["*.vue", "*.js", "*.jsx", "*.ts", "*.tsx"],
+      plugins: { i18nEasyVue },
+      languageOptions: {
+        parser: vueParser,
+        parserOptions
+      },
+      rules: {
+        "i18nEasyVue/i18n-transform": "error"
+      },
+      settings
+    };
+    const reactConfig = {
+      files: ["*.js", "*.jsx", "*.ts", "*.tsx"],
+      plugins: { i18nEasyReact },
+      languageOptions: {
+        parser: espree,
+        parserOptions
+      },
+      rules: { "i18nEasyReact/i18n-transform": "error" },
+      settings
+    };
+    const res = this.linter.verifyAndFix(fileContent, type == "vue" ? vueConfig : reactConfig, fileName);
+    return {
+      newFileContent: res.output,
+      // 转换后的文件内容（如果未应用修复，可能与输入内容相同）
+      fixed: res.fixed
+      // 是否应用了修复
+    };
+  }
+};
+export {
+  AstTransformer
+};

package/esm/eslint/react/i18n_easy_plugin.d.ts

@@ -0,0 +1,3 @@
+import type { ESLint } from 'eslint';
+declare const ReactPlugin: ESLint.Plugin;
+export default ReactPlugin;