@pinhao/auto-i18n-cli

v1.0.3

Published

a month ago

## 项目简介

Downloads

0High
0Medium
0Low

pinhao

i18n vue react automation cli translation

Auto-i18n-CLI 项目文档

项目简介

auto-i18n-cli 是一个基于 TypeScript 开发的自动化国际化（i18n）迁移工具。它旨在帮助开发者将遗留的 Vue 2/3 和 React 项目快速迁移到国际化支持状态。

该工具通过 AST（抽象语法树）解析代码，自动识别并提取中文文本，调用腾讯云翻译 API 进行翻译，并以非破坏性的方式将代码中的硬编码中文替换为 i18n 键值引用（如 $t('key')）。

文档目录

为了方便阅读和维护，文档按模块进行了拆分：

快速开始 / 使用说明
- 安装步骤
- 配置文件详解 (i18n.config.js)
- CLI 命令说明
- 运行示例
架构设计与运行逻辑
- 核心架构图
- 8 阶段处理流程详解
- 核心模块说明 (Director, Parsers, Transformer)
- 关键技术点 (AST, MagicString)
开发指南
- 项目目录结构
- 开发规范与原则
- 调试与测试

核心特性

多框架支持: 完美支持 Vue 2 (Options API), Vue 3 (Composition API/Script Setup), React (JSX/TSX), 以及纯 JS/TS 文件。
零侵入性: 严格遵循“零侵入”原则，使用 magic-string 进行基于 AST 的精确替换，保留原始代码格式、注释和空白。
智能提取:
- 自动识别模板文本、属性值、脚本字符串。
- 智能切分：仅去除首尾空白，保留标点符号和数字在翻译文本中，以维护语境完整性（如 放行时间(天): 整体提取）。
- 模板内混合文本整体提取（如 <p>测试2下</p>）。
自动依赖注入:
- 自动检测并注入 $t 函数引用 (React/JS/Vue3)。
- 支持自定义注入语句。
三级键值查找:
- 优先复用通用词库 (Common) 和现有词条 (Existing)，最后才调用翻译 API。
- 支持 多公共词库文件 加载与合并。
- 支持 outputRoot 配置，将翻译数据写入指定对象下。
- 提供 Global/Scope 两种复用策略，灵活控制跨模块复用行为。
审计报告: 每次运行生成详细的日志文件，记录所有变更、新增词条和潜在问题。

使用说明

安装

由于这是一个 CLI 工具，建议在项目中作为开发依赖安装，或使用 npx 直接运行。

# 安装依赖
npm install
# 或者
yarn install

全局安装与使用 (支持老项目)

对于不想在项目中安装依赖的老项目，你可以将 auto-i18n-cli 安装到全局环境。

# 全局安装
npm install -g auto-i18n-cli
# 或者
yarn global add auto-i18n-cli

安装完成后，你可以在任何项目目录下直接运行 auto-i18n 命令，无需在目标项目中安装任何依赖。

# 在老项目中运行
cd my-legacy-project
auto-i18n -c i18n.config.js

CLI 命令详解

auto-i18n 支持多种命令行参数，用于灵活控制运行行为。

| 参数 | 简写 | 说明 | 示例 | | :--- | :--- | :--- | :--- | | --config | -c | 指定配置文件路径 | -c ./config/i18n.js | | --entry | -e | 指定扫描入口 (覆盖配置) | -e src/pages/Home.vue | | --log-dir | -l | 指定日志输出目录 | -l ./logs | | --dry-run | -d | 空跑模式：仅扫描和模拟替换，不修改任何文件 | -d | | --help | -h | 查看帮助信息 | -h |

常用命令示例

1. 使用指定配置文件运行

auto-i18n -c i18n.config.js

2. 仅扫描特定文件 (调试用)

auto-i18n -e src/views/About.vue

3. 空跑模式 (Dry Run) 在不修改代码的情况下，查看会有哪些变更。非常适合在正式运行前进行检查。

auto-i18n -d

运行后，请查看生成的日志文件以确认提取和替换计划是否符合预期。

配置文件 (i18n.config.js)

在项目根目录下创建 i18n.config.js 文件。这是工具运行的核心配置文件。

module.exports = {
  // [必填] 扫描入口
  // 支持三种写法：
  // 1. 标准 Glob 模式: ['src/**/*.{vue,js,ts,jsx,tsx}']
  // 2. 目录简写 (推荐): ['src/views/'] -> 自动补全为 src/views/**/*.{vue,js,ts,jsx,tsx}
  // 3. 自定义 Glob: ['src/**/*.vue'] -> 仅扫描 vue 文件
  entry: ['src/views/'],
  
  // [必填] 中文语言包输出路径
  output: 'src/locales/zh-CN.json',

  // [可选] 输出根对象 Key
  // 如果设置，翻译内容将写入该对象下，而不是直接写入文件根目录。
  // 适用于需要将翻译数据嵌套在特定对象中的场景。
  outputRoot: 'extraConfig',
  
  // [必填] 基础目录，用于计算模块命名空间
  // 例如文件 src/views/Home.vue，baseDir 为 src，则模块名为 views.home
  baseDir: 'src',

  // [可选] 公共词库路径
  // 支持单个字符串或数组。如果配置了数组，会合并所有文件的内容。
  // common: 'src/locales/common.json',
  common: ['src/locales/common-base.json', 'src/locales/common-biz.json'],

  // [可选] 公共词库匹配策略
  // 'global' (默认): 全局递归查找，只要公共词库里有这个文案，不管在哪个模块下都会复用。
  // 'scope': 严格匹配，只有当公共词库中的文案位于当前文件所属的模块下时，才会复用。
  commonMatchStrategy: 'global',
  
  // 日志输出目录 (可选，默认为 'logs')
  // 如果设置为 false，则不输出日志文件
  logDir: 'custom-logs',
  
  // 命名空间深度，决定 key 的层级
  depth: 2, 

  // [可选] 忽略的属性名列表
  // 支持普通属性 (如 'label') 和指令参数 (如 'other-functions' 对应 :other-functions="...")
  ignoreAttributes: ['style', 'class', 'form', 'other-functions'],

  // [可选] 忽略的方法名列表
  // 调用这些方法时，其参数中的中文将不会被提取
  ignoreMethods: ['console.log', 'download'],
  
  // 转换规则配置
  rules: {
    // 是否开启自动注入依赖
    autoImport: true,
    
    // JS/TS/React/Vue3 Setup 中注入的引用语句
    // 如果检测到使用了 $t() 但未定义，会自动在头部插入此语句
    // 默认使用 $t，如需使用 t 请修改此处并自行处理代码替换逻辑
    jsImportStatement: "import { $t } from '@/i18n';",
  },
  
  // 腾讯云翻译配置 (可选，如果不配置将无法自动翻译)
  tencent: {
    secretId: "YOUR_SECRET_ID",
    secretKey: "YOUR_SECRET_KEY",
    region: "ap-shanghai", // 可选
    projectId: 0, // 可选
  },
};

高级配置说明

扫描入口 (Entry) 配置

entry 字段支持极高的灵活性，您可以根据需要混合使用以下三种模式：

目录简写 (推荐)
- 写法: 指定一个目录路径（以 / 结尾或指向存在的目录）。
- 行为: 工具会自动追加默认的文件匹配后缀 **/*.{vue,js,ts,jsx,tsx}。
- 示例: ['src/views/'] 等同于 ['src/views/**/*.{vue,js,ts,jsx,tsx}']。
自定义 Glob 模式
- 写法: 路径字符串中包含 * 通配符。
- 行为: 工具会完全按照您编写的规则进行匹配，不会自动追加后缀。
- 示例: ['src/**/*.vue'] (仅扫描 Vue 文件)，['src/utils/*.ts'] (仅扫描 utils 根目录下的 TS 文件)。

混合使用

示例:

entry: [
  'src/views/',             // 简写：扫描 views 下所有支持的文件
  'src/legacy/**/*.js',     // 自定义：只扫描 legacy 下的 js
  'src/components/Base.vue' // 精确：只扫描特定文件
]

运行命令

常用参数

-c, --config <path>: 指定配置文件路径 (默认为 i18n.config.js，如果文件在根目录可省略)。
-l, --log-dir <path>: 指定日志输出目录 (覆盖配置文件中的 logDir)。
-d, --dry-run: 试运行，不修改文件。

运行结果

运行完成后，工具会输出：

终端摘要: 显示扫描文件数、修改文件数、新增词条数等统计信息。
日志文件: 在 logs/ 目录下生成 process_YYYY-MM-DD...log 文件，包含详细的执行记录、替换详情和新增的 JSON 结构。
语言包更新: 指定的 zh-CN.json 文件会被更新，新增的翻译词条会自动写入。
代码变更: 源代码文件中的中文会被替换为 $t('...')，并根据需要自动注入 import 语句。

常见问题

1. 为什么我的文件没有被修改？

检查 entry 配置是否正确匹配到了文件。
检查文件中是否确实包含中文字符。
工具会自动跳过已经包含在 t('...') 或 $t('...') 中的中文。
检查日志文件中的 [扫描] 部分，确认文件是否被正确识别。

2. 自动注入的 import 语句不正确？

请在 i18n.config.js 的 rules.jsImportStatement 中配置符合你项目规范的引入语句。

3. 翻译结果不准确？

机器翻译仅供参考。工具生成的 Key 和翻译值都保存在 JSON 文件中，你可以随时手动校对和修改 JSON 文件。工具下次运行时会优先复用已有的 Key。