Rollup I18n Auto Create Plugin (Vite Plugin)

这是一个针对 Vue3 + Vite 开发环境设计的 i18n 自动化插件。它能够自动识别项目代码（.vue, .js, .ts, .jsx, .tsx）中的中文字符串，将其替换为国际化调用函数（如 t('key')），并自动维护语言映射文件。

功能特点

• 全场景支持：支持 Vue 模板、Script 脚本、JSX/TSX 语法。
• 智能替换：自动处理普通字符串、模板字符串（Template Literals）以及 JSX 属性/文本。
• 自动化维护：开发环境下实时提取并更新 zh-CN 映射文件；打包时可同步整理多语言包。
• 安全过滤：自动排除 console.log、alert 中的中文，避免干扰调试。
• 特殊符号兼容：自动转义 @ 符号（@@），完美兼容 vue-i18n 的链接消息语法。
• 高度可定制：支持自定义 Key 生成规则（长度、加密密钥、前缀等）。
• 顺序保留与清理：写入语言文件时尽量保留 Key 的插入顺序，并可自动清理代码中未再使用的 Key。

安装

npm install rollup-i18n-auto-create-plugin -D
# 或者
pnpm add rollup-i18n-auto-create-plugin -D

使用方法

在 vite.config.ts 中配置：

import RollupI18nCreatePlugin from 'rollup-i18n-auto-create-plugin'

export default defineConfig({
  plugins: [
    RollupI18nCreatePlugin({
      i18nPath: 'src/locales/zh-CN.ts',
      langPath: ['src/locales/en.ts'],
      injectToJS: `import { useI18n } from '@/hooks/web/useI18n'\nconst { t } = useI18n()`,
      excludes: ['locale', 'useI18n', 'node_modules'],
      jsText: 't',
      tempText: 't',
      regi18n: 'useI18n',
      delay: 1000,
      runBuild: true,
      // 新增配置项
      keyLength: 16,
      cryptoKey: 'your-secret-key',
      preText: 'APP_',
      cleanUnusedKeys: true
    }),
  ]
})

配置项说明

| 参数 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | i18nPath | string | src/locales/zh-CN.ts | 主语言文件（通常是中文）的存储路径 | | langPath | string[] | ['src/locales/en.ts'] | 其他语言文件的路径数组（打包时同步更新 Key） | | tempText | string | t | 模板中生成的国际化函数名 | | jsText | string | t | JS/TS 脚本中生成的国际化函数名 | | regi18n | string | useI18n | 用于判断文件是否已引入国际化钩子的标识符 | | injectToJS | string | (详见说明) | 自动注入到 Script 顶部的引入代码 | | excludes | string[] | ['locale', 'useI18n'] | 排除的文件名或路径片段 | | delay | number | 1000 | 开发环境下处理文件的防抖延迟（ms） | | reserveKeys | string[] | [] | 生产环境下需要保留（不被清理）的 Key | | runBuild | boolean | false | 打包时是否执行语言文件整理和同步 | | keyLength | number | 16 | 生成 Key 的哈希长度 | | cryptoKey | string | i18n | 用于生成哈希的 HMAC 密钥 | | preText | string | '' | 生成 Key 前在原文前增加的固定前缀 | | cleanUnusedKeys | boolean | true | 是否在写入语言文件前自动删除代码中未使用、且不在 reserveKeys 中的 Key |

Key 顺序与未使用 Key 清理

插件内部使用 Map 维护语言映射，写入语言文件时会按加载和新增的插入顺序输出 Key。开发环境会先读取 i18nPath 中已有内容，再把新识别到的中文追加到末尾。

cleanUnusedKeys 默认为 true，插件会根据当前扫描到的代码引用清理语言文件中未使用的 Key。如果你的项目里有运行时动态拼接的 Key、服务端下发的 Key、或暂时不在代码中出现但仍需要保留的 Key，请使用 reserveKeys 保留，或者将 cleanUnusedKeys 设置为 false。

RollupI18nCreatePlugin({
  cleanUnusedKeys: false,
  reserveKeys: ['dynamic_title', 'server_message']
})

本地项目测试

你可以先在插件项目中构建并运行测试：

npm run build
npm test

然后在业务项目中使用本地版本联调，推荐以下两种方式。

方式一：使用 npm link

在插件项目根目录执行：

npm run build
npm link

在你的业务项目根目录执行：

npm link rollup-i18n-auto-create-plugin

之后业务项目的 vite.config.ts 仍然正常引入包名即可。每次修改插件源码后，需要回到插件项目重新执行：

npm run build

然后重启业务项目的 Vite 开发服务。

方式二：使用 file 本地依赖

在业务项目的 package.json 中临时指定本地路径：

{
  "devDependencies": {
    "rollup-i18n-auto-create-plugin": "file:../rollup-i18n-auto-create-plugin"
  }
}

然后重新安装依赖：

npm install

这种方式更接近真实安装包行为。修改插件后同样需要先在插件项目执行 npm run build，再在业务项目重新安装或刷新依赖。

工作原理

1. 解析阶段：利用 @vue/compiler-sfc 解析 .vue 文件，使用 Babel (@babel/parser) 解析 JS/TS/JSX 代码。
2. 提取阶段：递归遍历 AST（抽象语法树），识别所有未被排除的中文字符串。
3. 生成阶段：
   • 根据原文 + preText + cryptoKey 生成唯一哈希作为 Key。
   • 将原文内容存入 i18nPath 指定的文件，并按插入顺序写回。
   • 针对包含 @ 的文本自动转义为 @@，防止 vue-i18n 报错。
4. 替换阶段：将代码中的中文字符串改写为配置的 t('key') 调用。
5. 清理阶段：当 cleanUnusedKeys 为 true 时，写入前会删除未被当前代码引用、且不在 reserveKeys 中的 Key。

注意事项

• 开发环境刷新：由于为了性能考虑加入了 1s 的防抖处理，修改中文后页面刷新会有微小延迟。
• 未使用 Key 清理：cleanUnusedKeys 默认开启，首次在老项目中使用前建议先提交或备份语言文件，避免误删动态 Key。
• @ 符号处理：插件会自动处理文本中的 @ 符号，确保在 vue-i18n 中能正常渲染为原样文本。
• 老项目迁移：如果你需要将已有的 t('key') 代码还原回中文，可以参考 src/migrate.ts 迁移脚本。

迁移工具

如果你需要将一个已经手动写满 t('key') 的老项目转化回中文（以便配合本插件使用），可以使用 src/migrate.ts 脚本。

该脚本已进行优化，支持：

1. 递归扫描：自动遍历 src 目录下的所有 .vue, .ts, .js, .tsx, .jsx 文件。
2. 插值表达式还原：将 {{ t('key') }} 还原为中文。
3. 属性绑定还原：将 :title="t('key')" 还原为静态属性 title="中文"（原版文档中提到的无法转化的问题已解决）。
4. 脚本代码还原：将 Script 或 JS 文件中的 t('key') 调用还原为字符串 '中文'。

使用说明： 由于每个项目的路径配置不同，请在使用前修改 src/migrate.ts 中的 options 配置（如语言包路径、源码目录等）。

许可证

MIT