原创 LaiYoung_ 2025-10-14 08:30 重庆

当前虽有各类 AI 工具可辅助处理此类问题，但受限于效果稳定性与适配精准度，往往难以满足项目实际需求。而本工具的处理效果稳定可控，可将国际化适配的整体效率提升 80%~90%。

点击关注公众号，“技术干货” 及时达！

前言在全球化协作持续深化的大背景下，越来越多前端项目对国际化适配提出了快速落地的需求。然而，许多项目在初期规划阶段并未纳入国际化方案，导致代码中遗留了大量中文硬编码——这类硬编码广泛分布于各类文件中，数量少则上千，多则可达四五千甚至更多。

若依赖人工逐文件排查、提取中文并替换为支持语言包动态切换的写法，不仅需耗费大量时间，且工作内容重复机械，缺乏技术价值。为此，我开发了一套支持高度自定义配置的 JavaScript 脚本 CLI 工具 fe-js-utils[1]，可实现四大核心功能：自动从项目中提取中文文本、提炼公共语言模块、对语言模块进行智能分类，以及自动替换代码中的中文硬编码。

以下为具体使用效果展示：

fe-js-utils 使用手册fe-js-utils 是一个前端代码质量检测和国际化处理的 JavaScript 工具集，提供了多种实用功能帮助开发者提高代码质量和实现国际化。

一、安装依赖

npm install fe-js-utils --save-dev
# 或
yarn add fe-js-utils -D

二、配置脚本命令在 package.json 中添加以下 scripts：

{
  "scripts": {
    "cleanInvalidComments": "fe-js-utils cleanInvalidComments",
    "checkAny": "fe-js-utils checkAny",
    "extractChinese": "fe-js-utils extractChinese",
    "extractCommonLocaleValues": "fe-js-utils extractCommonLocaleValues",
    "findModuleInCommonLocaleValues": "fe-js-utils findModuleInCommonLocaleValues",
    "autoGenerateLocaleModules": "fe-js-utils autoGenerateLocaleModules",
    "autoReplaceChinese": "fe-js-utils autoReplaceChinese"
  }
}

三、配置文件创建步骤说明在项目根目录创建 fe-js-utils.config.ts

使用以下基础模板（示例）：

// fe-js-utils.config.ts
const path = require('path');

module.exports = {
  checkAny: {
    targetDir: './src',
    outputFile: path.join(process.cwd(), 'check-any-results.js'),
    skipSet: [],
    extFiles: ['.ts', '.vue']
  },
  cleanInvalidComments: {
    targetDir: './src',
    extFiles: ['.js', '.ts', '.vue']
  },
  extractChinese: {
    targetDir: './src',
    outputFile: path.join(process.cwd(), 'extract-chinese-results.js'),
    extFiles: ['.js', '.ts', '.vue'],
    excludeFiles: [],
    excludeDirs: []
  },
  extractCommonLocaleValues: {
    outputFile: './src/locales/zh_CN/Common.ts'
  },
  findModuleInCommonLocaleValues: {
    localeDir: './src/locales/zh_CN',
    commonLocaleModule: 'Common',
    localModules: ['ObjectConstruction', 'DataDirectoryMgmt']
  },
  autoGenerateLocaleModules: {
    outputDir: './src/locales/zh_CN',
    runExtractFirst: true
  },
  autoReplaceChinese: {
    localeDir: './src/locales/zh_CN',
    commonLocaleModule: 'Common',
    localModules: ['ObjectConstruction', 'DataDirectoryMgmt'],
    customImportStatements: (imports: string[], filePath: string, localModule: string) => {
      // 自定义 import 语句的回调，返回一个 import 语句字符串的数组，为空时不会添加任何 import 语句
      return [];
    },
    customVariableDeclarations: (fileContent: string, filePath: string, localModule: string, needsCommon: boolean) => {
      // 自定义 变量声明 的回调，返回一个变量声明字符串的数组，为空时不会添加任何变量声明
      return '';
    },
    customReplaceTextFunction: (
      filePath: string,
      localModule: string,
      chineseKey: string,
      englishValue: string,
      isInCommon: boolean,
      context: string
    ) => {
      // 自定义 替换中文字符 的回调，返回一个替换后的字符串，为空时将不会替换任何中文字符
      // 示例：
      return `$t('${localModule}.${englishValue}')`;
    }
  }
};

「注意事项：」

使用 .ts 文件时，Node 版本需要 >= v22.18.0，使用 .js 无要求；

在 fe-js-utils.config 配置文件中 import ts 文件请添加 .ts 后缀

四、工具及配置项说明checkAny（Any 类型检查）「功能」：扫描项目中的 any 类型的使用「使用场景」：

代码质量检查

TypeScript 类型规范审计

「配置项说明：」

配置项

类型

默认值

说明

targetDir

string

'./src'

需要扫描的源码目录

outputFile

string

${process.cwd()}/check-any-results.js

结果输出文件路径

skipSet

string[]

[]

需要跳过的代码模式（包含这些字符串的代码行将不被检测）

extFiles

string[]

['.ts', '.vue']

需要扫描的文件扩展名

使用方式

# 执行 any 类型检查
npm run checkAny
# 或
yarn checkAny

配置示例

// fe-js-utils.config.ts
module.exports = {
  checkAny: {
    // 需要扫描的源码目录
    targetDir: './src',
    // 结果输出文件路径
    outputFile: './check-any-results.js',
    // 需要跳过的代码模式
    skipSet: ['cancelCb?: (error: any) => void;', 'valueComponent?: any;'],
    // 需要扫描的文件扩展名
    extFiles: ['.ts', '.vue']
  }
};

输出格式生成的 check-any-results.js 文件格式如下：

// src/components/user/UserService.ts
['value?: any;', 'fail?: (err: any) => void;'];

// src/components/alarm/AlarmService.ts
['let obj: any = "";'];

cleanInvalidComments（无效注释清理）「功能」：清理无效的 JSDoc 注释「清理规则」：

自动清理/** ... */格式没有描述的@param及@returns

「配置项说明：」

配置项

类型

默认值

说明

targetDir

string

'./src'

需要清理注释的源码目录

extFiles

string[]

['.js', '.ts', '.vue']

需要处理的文件扩展名

使用方式

# 执行注释清理
npm run cleanInvalidComments
# 或
yarn cleanInvalidComments

配置示例

// fe-js-utils.config.ts
module.exports = {
  cleanInvalidComments: {
    // 需要清理注释的源码目录
    targetDir: './src',
    // 需要处理的文件扩展名
    extFiles: ['.js', '.ts', '.vue']
  }
};

extractChinese（中文提取）「功能」：提取项目中的中文字符「使用场景」：

方便快速国际化的适配

识别项目中所有硬编码的中文文案

为后续的国际化处理提供数据基础

「配置项说明：」

配置项

类型

默认值

说明

targetDir

string

'./src'

需要扫描的源码目录

outputFile

string

${process.cwd()}/extract-chinese-results.js

结果输出文件路径

extFiles

string[]

['.js', '.jsx', '.ts', '.tsx', '.vue', '.html']

需要扫描的文件扩展名

excludeDirs

string[]

['node_modules', 'dist', 'build', 'locales']

需要排除的目录

excludeFiles

string[]

['extract-chinese-results.js', 'extract-chinese.js']

需要排除的特定文件

verbose

boolean

false

是否显示处理过程日志

使用方式

# 执行中文提取
npm run extractChinese
# 或
yarn extractChinese

配置示例

// fe-js-utils.config.ts
module.exports = {
  extractChinese: {
    // 需要扫描的源码目录
    targetDir: './src',
    // 结果输出文件路径
    outputFile: './extract-chinese-results.js',
    // 需要扫描的文件扩展名
    extFiles: ['.js', '.ts', '.vue'],
    // 需要排除的目录
    excludeDirs: ['node_modules', 'dist', 'build', 'locales'],
    // 需要排除的特定文件
    excludeFiles: ['extract-chinese-results.js'],
    // 显示详细处理过程日志
    verbose: false
  }
};

输出格式生成的 extract-chinese-results.js 文件格式如下：

// src/components/user/UserList.vue
['用户管理', '新增用户', '编辑用户'];

// src/components/alarm/AlarmList.vue
['报警列表', '报警级别', '处理状态'];

extractCommonLocaleValues（提取公共语言包）「功能」：从 extractChinese 的输出结果中提取重复出现的中文字符串，并生成公共语言包模块文件「使用场景」：

自动识别项目中多处使用的相同文案

生成公共语言包，避免重复定义

为国际化提供共享的通用文案

「配置项说明：」

配置项

类型

默认值

说明

inputFile

string

extractChinese.outputFile

输入文件路径（中文提取结果文件）

outputFile

string

'./src/locales/zh_CN/Common.ts'

输出文件路径（公共语言包文件）

verbose

boolean

false

是否显示处理过程日志

使用方式

# 执行公共语言包提取
npm run extractCommonLocaleValues
# 或
yarn extractCommonLocaleValues

配置示例

// fe-js-utils.config.ts
module.exports = {
  extractCommonLocaleValues: {
    // 输出文件路径
    outputFile: './src/locales/zh_CN/Common.ts',
    // 显示详细处理过程日志
    verbose: false
  }
};

输出格式生成的公共语言包文件格式如下：

export default {
  key0: '确定',
  key1: '取消',
  key2: '保存',
  key3: '删除'
};

注意事项由于目前翻译插件的一些限制，无法进行大批量翻译处理，所以生成的语言文件中的 key 为自增的 keyIndex，请自行使用 ChatGPT 或 DeepSeek 等 AI 工具进行翻译处理。

findModuleInCommonLocaleValues（查找指定模块与公共模块重复值）「功能」：找出指定模块中与公共模块（Common）中定义相同的中文值「使用场景」：

检测模块中哪些文案已在公共模块中定义

识别可以复用公共文案的地方

避免重复定义相同的国际化文案

「配置项说明：」

配置项

类型

默认值

说明

localeDir

string

'./src/locales/zh_CN'

语言包文件所在目录

localModules

string[]

[]

需要检查的模块文件名列表

commonLocaleModule

string

'Common'

公共语言包模块文件名

annotationDefinedInCommonLocale

boolean

false

是否在 localModules 中注释掉在 commonLocaleModule 中已存在的定义

verbose

boolean

false

是否显示处理过程日志

使用方式

# 查找模块与公共模块的重复值
npm run findModuleInCommonLocaleValues
# 或
yarn findModuleInCommonLocaleValues

配置示例

// fe-js-utils.config.ts
module.exports = {
  findModuleInCommonLocaleValues: {
    // 语言包目录
    localeDir: './src/locales/zh_CN',
    // 需要检查的模块列表
    localModules: ['UserManagement', 'AlarmConfig', 'DataDirectory'],
    // 公共模块名称
    commonLocaleModule: 'Common',
    // 是否在 localModules 中注释掉在 commonLocaleModule 中已存在的定义
    annotationDefinedInCommonLocale: true,
    // 显示详细处理过程日志
    verbose: false
  }
};

输出格式输出结果格式如下：

============find-common-locale-values============

UserManagement 中在 Common 中出现过的值:
[
  "确定",
  "取消",
  "保存",
  "删除"
]

总共找到 4 个相同的值

autoGenerateLocaleModules（自动生成国际化模块文件）「功能」：根据 extractChinese 提取的中文结果自动生成国际化模块文件

「使用场景」：

自动化生成国际化语言包

按模块划分语言资源

快速构建项目国际化基础结构

「配置项说明：」

配置项

类型

默认值

说明

inputFile

string

extractChinese.outputFile 的值

中文提取结果文件路径（通常自动从 extractChinese 配置中获取）

outputDir

string

'./src/locales/zh_CN'

生成的语言包文件输出目录

verbose

boolean

false

是否显示详细处理过程日志

runExtractFirst

boolean

false

是否在生成前自动执行中文提取操作

autoExtractCommonLocale

boolean

true

是否自动提取公共语言包

annotationDefinedInCommonLocale

boolean

true

是否对已在公共语言包中定义的中文进行注释标记

customModuleDefinitions

object

{}

允许用户自定义模块命名规则，格式为 { moduleName: filePathPrefix }。将特定路径前缀映射到指定的模块名称，键为模块名称，值为文件路径前缀，未定义的将按照默认规则处理。

使用方式1. 基础使用（依赖已有的提取结果）首先确保已通过 extractChinese 命令生成了中文提取结果文件：

# 先执行中文提取
npm run extractChinese
# 或
yarn extractChinese

# 再生成国际化模块
npm run autoGenerateLocaleModules
# 或
yarn autoGenerateLocaleModules

2. 自动提取并生成（推荐）配置 runExtractFirst: true 后，工具会自动先执行中文提取再生成模块：

# 一条命令完成中文提取和模块生成
npm run autoGenerateLocaleModules
# 或
yarn autoGenerateLocaleModules

配置示例

// fe-js-utils.config.ts
module.exports = {
  extractChinese: {
    targetDir: './src',
    outputFile: './extract-chinese-results.js',
    extFiles: ['.js', '.ts', '.vue'],
    excludeDirs: ['node_modules', 'dist', 'build', 'locales']
  },

  autoGenerateLocaleModules: {
    // 输入文件路径（中文提取结果文件）
    inputFile: './extract-chinese-results.js',
    // 语言包输出目录
    outputDir: './src/locales/zh_CN',
    // 显示详细日志
    verbose: false,
    // 在生成前自动执行中文提取
    runExtractFirst: true,
    // 自动提取公共语言包
    autoExtractCommonLocale: true,
    // 对已在公共语言包中定义的中文进行注释标记
    annotationDefinedInCommonLocale: true,
    // 自定义模块定义规则
    customModuleDefinitions: {
      Notice: 'src/components/alarm-notice',
      Directory: 'src/components/common-directory-view',
      StructureField: 'src/components/structure-field-table'
    }
  }
};

生成规则1. 模块命名规则默认根据文件路径自动生成模块名：

路径：src/components/user-management/UserList.vue

模块名：UserManagement（取第三级目录名并转为大驼峰命名）

如果配置了 customModuleDefinitions，则优先使用自定义规则：

配置：{ Notice: 'src/components/alarm-notice' }

与 src/components/alarm-notice 文件路径相关的所有文件都会归类到 Notice 模块，例如：

src/components/alarm-notice.vue

src/components/alarm-notice.ts

src/components/alarm-notice/alarm-notice-detail/index.vue

src/components/alarm-notice/table-field-selector-dialog/index.vue

模块名：Notice（使用自定义模块名）

2. 文件结构示例输入文件（extract-chinese-results.js）：

// src/components/user-management/UserList.vue
['用户管理', '新增用户', '编辑用户'];

// src/components/alarm-config/AlarmSetting.vue
['报警配置', '保存设置', '取消'];

输出文件结构：

localesDir/
├── UserManagement.ts
└── AlarmConfig.ts

输出文件内容（UserManagement.ts）：

export default {
  // src/components/user-management/UserList.vue
  key0: '用户管理',
  key1: '新增用户',
  key2: '编辑用户'
};

注意事项生成 index.ts 文件，需要手动注册到 i18n 或其他语言包管理工具中；

由于目前翻译插件的一些限制，无法进行大批量翻译处理，所以生成的语言文件中的 key 为自增的 keyIndex，请自行使用 ChatGPT 或 DeepSeek 等 AI 工具进行翻译处理。

autoReplaceChinese（自动替换项目中的中文文案）「功能」：根据语言包文件自动替换源代码中的中文字符串为国际化调用函数「使用场景」：

自动化完成项目国际化改造

将硬编码的中文字符串替换为动态调用

统一项目中文案的使用方式

「配置项说明：」

配置项

类型

默认值

说明

localeDir

string

'./src/locales/zh_CN'

语言包文件所在目录

localModules

string[]

[]

需要处理的语言模块文件名列表，对应 LLMT 枚举的值

commonLocaleModule

string

'Common'

公共语言包模块文件名

variableDeclarationInsertPosition

string

'// #region Hooks'

变量声明插入位置标记，如果值为空或在文件中未找到，则插入到 import 语句的最后

verbose

boolean

false

是否显示处理过程日志

customImportStatements

function

null

自定义 import 语句回调函数

customVariableDeclarations

function

null

自定义变量定义语句回调函数

customReplaceTextFunction

function

null

自定义文本替换回调函数

使用方式

# 自动替换项目中的中文文案
npm run autoReplaceChinese
# 或
yarn autoReplaceChinese

配置示例

// fe-js-utils.config.ts
module.exports = {
  autoReplaceChinese: {
    // 语言包目录
    localeDir: './src/locales/zh_CN',
    // 需要处理的模块列表
    localModules: ['UserManagement', 'AlarmConfig', 'DataDirectory'],
    // 公共模块名称
    commonLocaleModule: 'Common',
    // 变量声明插入位置，默认为 // #region Hooks，如果值为空或在文件中未找到，则插入到 import 语句的最后
    variableDeclarationInsertPosition: '// #region Hooks',
    // 显示详细日志
    verbose: false,
    // 自定义 import 语句的回调函数
    customImportStatements: (imports: string[], filePath: string, localModule: string) => {
      // 返回一个 import 语句字符串的数组，为空时不会添加任何 import 语句
      return [];
    },
    // 自定义变量声明的回调函数
    customVariableDeclarations: (fileContent: string, filePath: string, localModule: string, needsCommon: boolean) => {
      // 返回一个变量声明字符串，为空时不会添加任何变量声明
      return '';
    },
    // 自定义替换文本的回调函数
    customReplaceTextFunction: (
      filePath: string,
      localModule: string,
      chineseKey: string,
      englishValue: string,
      isCommon: boolean,
      context: string
    ) => {
      // 返回一个替换后的字符串，为空时将不会替换任何中文字符
      // 示例：
      return `$t('${localModule}.${englishValue}')`;
    }
  }
};

注意事项「语言文件格式」：确保语言文件遵循指定格式，包含文件路径注释和键值对

「源文件结构」：源文件中需要有 // #region Hooks 注释标记 hook 插入位置

「依赖项」：如果没有实现几个对应的「自定义替换函数」，则项目中需要存在 useLocalLang hook 和 LLMT 枚举类型

「备份文件」：建议在执行前备份源文件，防止替换错误

「逐步执行」：建议先在少数模块上测试，确认效果后再批量处理

「自定义函数」：

customImportStatements：用于自定义添加的 import 语句，回调参数为 (existingImports: string[], filePath: string, localModule: string)

customVariableDeclarations：用于自定义添加的变量声明，回调参数为 (fileContent: string, filePath: string, localModule: string, needsCommon: boolean)

customReplaceTextFunction：用于自定义文本替换逻辑，回调参数为 (filePath: string, localModule: string, chineseKey: string, englishValue: string, isCommon: boolean, context: string)

不支持格式化字符串处理，需要手动处理

执行效果执行前：

<template>
  <div>
    <el-button @click="save">保存</el-button>
    <el-button @click="cancel">取消</el-button>
  </div>
</template>

<script>
// #region Hooks

export default {
  methods: {
    save() {
      this.$message.success('保存成功');
    },
    cancel() {
      this.$emit('cancel');
    }
  }
};
</script>

执行后：

<template>
  <div>
    <el-button @click="save">{{ localLang('save') }}</el-button>
    <el-button @click="cancel">{{ localLang('cancel') }}</el-button>
  </div>
</template>

<script>
import { useLocalLang } from '@/hooks/UseLocalLang';
import { LLMT } from '@/model/bo/LocalBO';

// #region Hooks
const { localLang } = useLocalLang(LLMT.UserManagement);
// #endregion

export default {
  methods: {
    save() {
      this.$message.success(localLang('saveSuccess'));
    },
    cancel() {
      this.$emit('cancel');
    }
  }
};
</script>

国际化文案处理工具间的关系与组合使用指南这些工具按照国际化文案处理流程形成了一个完整的工具链，每个工具都有其特定的功能和作用。以下是它们之间的关系和推荐的组合使用方式：

工具间的关系「extractChinese（中文提取）」

「作用」：扫描整个项目源码，提取所有硬编码的中文文本

「输出」：生成 extract-chinese-results.js 文件，包含按文件组织的中文文本列表

「地位」：整个国际化流程的起点和数据源

「extractCommonLocaleValues（提取公共语言包）」

点击关注公众号，“技术干货” 及时达！

Fish AI Reader

FishAI

联系邮箱 441953276@qq.com

相关标签