imi-i18n

v1.0.11

Published

4 months ago

CLI tool for extracting internationalization texts from TypeScript projects

Downloads

0High
0Medium
0Low

vincentchris

i18n internationalization typescript cli excel

IMI-I18N 国际化文案提取工具

简介

IMI-I18N 是一个基于 Node.js + TypeScript 开发的CLI工具，用于自动提取TypeScript项目中的国际化文案，并将其导出到Excel文件中，便于翻译团队进行国际化文案管理。

特性

🔍 智能扫描: 自动识别TypeScript/React项目中的useTranslation钩子使用
📋 文案提取: 提取t()方法包裹的所有国际化文案，支持变量引用
🌿 Git集成: 基于Git分支自动提取需求号，支持团队协作流程
⚙️ 配置灵活: 自动读取项目配置，支持自定义项目代码
📊 Excel导出: 自动生成格式化的Excel文件，支持数据合并和更新
🎨 友好界面: 彩色终端输出，详细的进度提示和错误信息
🚀 平台集成: 集成国际化平台API，自动过滤已存在文案，避免重复工作
🏎️ 性能优化: 支持批量查询和并发控制，处理大量数据时性能优秀
🔧 智能配置: 支持普通项目和pnpm monorepo，配置文件自动存储在合适的位置

安装

📦 NPM 安装 (推荐)

# 全局安装
npm install -g imi-i18n

# 或者使用 yarn
yarn global add imi-i18n

# 或者使用 pnpm
pnpm add -g imi-i18n

🚀 快速开始

# 1. 在你的 TypeScript/React 项目根目录下运行
imi-i18n

# 2. 首次运行会提示配置 Excel 文件存放目录
# 3. 工具会自动扫描代码并生成 Excel 文件

# 查看帮助
imi-i18n --help

⚡ 使用 npx (无需安装)

# 直接运行，无需全局安装
npx imi-i18n

# 查看版本
npx imi-i18n --version

🔧 系统要求

Node.js >= 16.0.0
Git (用于分支检查)
TypeScript/React 项目

💻 本地开发

# 克隆项目
git clone https://github.com/VincentChris/imi-i18n.git
cd imi-i18n

# 安装依赖
pnpm install

# 构建项目
pnpm run build

# 全局链接 (可选)
npm link

使用方法

🎯 快速上手

# 1. 安装工具
npm install -g imi-i18n

# 2. 进入你的 TypeScript/React 项目目录
cd your-typescript-project

# 3. 确保你在一个 Git 分支上（非 master/main/dev）
git checkout -b REQ123_yourname

# 4. 运行工具
imi-i18n

# 5. 首次运行会提示设置 Excel 存放目录
# 6. 工具会自动扫描并生成 Excel 文件

基本用法

# 在当前目录执行（默认提取命令）
imi-i18n

# 显式使用提取命令
imi-i18n extract

# 指定扫描目录
imi-i18n extract -d /path/to/project

# 显示详细输出
imi-i18n extract -v

配置管理

💡 如果项目中没有 umirc.ts，可以在 .imi-i18n-config.json 中手动追加 projectCode 字段（例如 "projectCode": "pudo-client"），工具会在找不到 Umi 配置时使用该值写入 Excel。

# 显示当前配置
imi-i18n config show

# 设置Excel文件存放路径
imi-i18n config set-path

# 重置配置到默认值
imi-i18n config reset

# 设置国际化平台API配置
imi-i18n config set-api

# 显示API配置信息
imi-i18n config show-api

命令行选项

提取命令 (extract)

| 选项 | 描述 | 默认值 | |------|------|--------| | -d, --dir <path> | 指定扫描目录 | 当前目录 | | -e, --exclude <dirs...> | 排除的目录 | node_modules, .git, dist, build | | -v, --verbose | 显示详细输出 | false | | -f, --force | 强制写入所有文案，跳过平台查询 | false | | --dry-run | 预览模式，不实际写入Excel文件 | false |

配置命令 (config)

| 子命令 | 描述 | |--------|------| | show | 显示当前配置信息 | | set-path | 交互式设置Excel文件存放路径 | | reset | 重置配置文件到默认值 | | set-api | 设置国际化平台API配置 | | show-api | 显示API配置信息 |

使用示例

# 首次运行会提示配置Excel存放目录
imi-i18n

# 基本使用（自动查询平台过滤已存在文案）
imi-i18n extract

# 强制模式（跳过平台查询，写入所有文案）
imi-i18n extract --force

# 预览模式（查看将要写入的文案但不实际写入）
imi-i18n extract --dry-run

# 扫描指定目录，排除额外目录
imi-i18n extract -d ./src -e node_modules dist temp

# 详细模式，显示所有提取的文案
imi-i18n extract -v

# 查看当前配置
imi-i18n config show

# 修改Excel存放路径
imi-i18n config set-path

# 帮助信息
imi-i18n --help
imi-i18n extract --help
imi-i18n config --help

工作流程

0. 配置初始化

🔧 首次运行自动检测配置文件
📁 必须手动设置Excel文件存放目录（无默认值）
💾 保存配置到 ~/.imi-i18n-config.json
🔄 支持后续修改配置

1. Git分支检查

✅ 检测当前目录是否为Git仓库
✅ 获取当前分支名称
✅ 验证分支名格式并提取需求号
❌ 跳过特定分支：test, uat, master, dev

支持的分支名格式:

REQ123_zhangsan (推荐)
REQ123-zhangsan
需求号_开发者 或 需求号-开发者

2. 项目配置读取

🔍 从当前目录向上查找最近的umirc.ts配置文件
📖 提取projectCode配置项
🔧 未找到时使用默认值：ds-web-ds

3. 文件扫描与文案提取

📁 递归扫描.tsx和.ts文件
🔍 识别useTranslation钩子的使用
📝 提取t()方法包裹的国际化文案
🔗 处理变量引用和模板字符串

4. Excel文件生成

📊 检查/创建Excel文件：[用户配置目录]/[需求号].xlsx
📋 设置标准表头结构
🔄 合并现有数据，覆盖重复的textkey
💾 格式化输出，包含边框和样式

Excel文件结构

| 列名 | 说明 | 数据来源 | |------|------|----------| | projectCode | 项目代码 | 配置文件或默认值 | | moduleCode | 模块代码 | textkey 带已知模块前缀时取对应模块，否则为 "ALL" | | moduleName | 模块名称 | 随 moduleCode 从模块接口匹配，否则为 "ALL" | | moduleNameEn | 模块英文名 | 随 moduleCode 从模块接口匹配，否则为 "ALL" | | textkey | 文案键值 | t()方法提取；匹配模块前缀时会剥离 moduleCode.，无前缀时保持原文并归入 "ALL" | | country | 国家代码 | 固定值 "ALL" | | translationZh | 中文翻译 | t()方法内容 | | translationEn | 英文翻译 | 留空 |

识别模式

工具能够识别以下代码模式：

import { useTranslation } from 'react-i18next';

const Component = () => {
  const { t } = useTranslation();
  
  // 直接字符串
  const text1 = t('common.login');
  
  // 变量引用
  const loginKey = 'common.login';
  const text2 = t(loginKey);
  
  // 对象方法调用
  const text3 = i18n.t('common.logout');
  
  // JSX中使用
  return (
    <div>
      <span>{t('user.profile.title')}</span>
      <button>{t('common.submit')}</button>
    </div>
  );
};

也支持可静态解析的辅助函数封装：

const pageKey = (key: string) => `WestEuropeDashboard.${key}`;
const tPage = (key: string) => t(pageKey(key));

tPage('站点表现汇总'); // 提取为 WestEuropeDashboard.站点表现汇总

输出示例

成功执行

🚀 IMI-I18N 国际化文案提取工具

📁 目标目录: /path/to/project
🚫 排除目录: node_modules, .git, dist, build

⚙️  步骤 0: 加载用户配置...
📁 Excel存放目录: /Users/username/Documents/excel

🔍 步骤 1: 检查Git分支信息...
✅ 当前分支：REQ123_zhangsan
✅ 提取的需求号：REQ123

📄 步骤 2: 读取项目配置...
✅ 从配置文件获取projectCode: my-project

🔍 步骤 3: 扫描TypeScript文件...
✨ 找到国际化文案: common.login
✨ 找到国际化文案: common.logout
✅ 扫描完成，找到 2 个国际化文案

📊 步骤 4: 处理Excel文件...
✅ Excel文件写入完成

🎉 提取完成！
📋 汇总信息:
   - 当前分支: REQ123_zhangsan
   - 需求号: REQ123
   - 项目代码: my-project
   - Excel存放目录: /Users/username/Documents/excel
   - 提取文案数量: 2
   - Excel文件路径: /Users/username/Documents/excel/REQ123.xlsx

首次运行配置

🚀 IMI-I18N 国际化文案提取工具

📁 目标目录: /path/to/project
🚫 排除目录: node_modules, .git, dist, build

⚙️  步骤 0: 加载用户配置...
📝 首次运行，需要进行初始配置...

🔧 配置Excel文件存放目录
Excel文件将按需求号命名存放在指定目录中
⚠️  请手动输入一个有效的目录路径（必填）
示例: /Users/username/Documents/excel 或 ~/Documents/excel

? 请输入Excel文件存放目录路径: /Users/username/Documents/excel
✅ 配置已保存: /Users/username/.imi-i18n-config.json
✅ 已创建目录: /Users/username/Documents/excel
✅ 配置完成!

配置管理示例

# 显示配置
$ imi-i18n config show

📋 当前配置:
  Excel存放目录: /Users/username/Documents/excel
  最后修改时间: 2024-01-01 10:30:00
  配置文件位置: /Users/username/.imi-i18n-config.json

# 修改配置
$ imi-i18n config set-path

🔧 修改Excel文件存放目录
当前目录: /Users/username/Documents/excel
? 请输入新的Excel文件存放目录路径: /Users/username/Documents/new-excel
? 如果目录不存在是否自动创建? Yes
✅ 已创建目录: /Users/username/Documents/new-excel
✅ 配置已保存: /Users/username/.imi-i18n-config.json
✅ Excel存放目录已更新!

错误处理

⚠️  当前分支 "master" 在跳过列表中，请切换到功能分支后再执行
⚠️  当前目录不是Git仓库，跳过执行
⚠️  无法从分支名中提取需求号，请确保分支名格式为：需求号_开发者 或 需求号-开发者

开发

项目结构

imi-i18n/
├── src/
│   ├── index.ts           # CLI入口和主程序
│   ├── git.ts             # Git操作和分支检查
│   ├── scanner.ts         # 文件扫描和AST解析
│   ├── config.ts          # 配置文件读取
│   ├── excel.ts           # Excel文件操作
│   └── types.ts           # TypeScript类型定义
├── bin/
│   └── imi-i18n          # CLI可执行文件
├── dist/                  # 构建输出
├── package.json
├── tsconfig.json
└── README.md

开发命令

# 开发模式运行
pnpm run dev

# 构建项目
pnpm run build

# 类型检查
pnpm run typecheck

# 代码检查
pnpm run lint

技术栈

TypeScript: 类型安全的JavaScript
Commander.js: CLI框架
Simple-git: Git操作
@typescript-eslint/typescript-estree: AST解析
ExcelJS: Excel文件操作
Chalk: 终端彩色输出

配置文件示例

umirc.ts

export default {
  projectCode: 'my-project-code'
};

// 或者使用 defineConfig
import { defineConfig } from 'umi';

export default defineConfig({
  projectCode: 'my-project-code'
});

注意事项

分支命名: 请确保功能分支按照规范命名，如REQ123_zhangsan
权限要求: 需要有Excel文件输出目录的写入权限
Git仓库: 工具需要在Git仓库中运行
文件格式: 仅支持.tsx和.ts文件扫描
提取规则: 仅提取 t() 调用的首个参数写入 Excel，例如 t('已选择 {{count}} 个订单...', { count }) 只会记录 '已选择 {{count}} 个订单...'，其余插值或配置参数不会写入。对于 tPage('站点表现汇总') 这类静态辅助函数封装，会尽量解析成完整 key；无法静态确认的动态表达式会保留 ${...} 占位或跳过。

故障排除

常见问题

Q: 提示"当前目录不是Git仓库" A: 请在Git仓库根目录或子目录中执行命令

Q: 无法提取需求号 A: 请检查分支名格式，确保使用需求号_开发者或需求号-开发者格式

Q: 未找到配置文件 A: 工具会自动使用默认projectCode，或在项目中添加umirc.ts配置文件

Q: Excel文件写入失败 A: 请检查输出目录权限，确保Excel文件未被其他程序占用

许可证

MIT License

贡献

欢迎提交Issue和Pull Request来改进这个工具。

更新日志

v1.0.0

🎉 初始版本发布
✨ 支持TypeScript文件扫描
✨ Git分支集成
✨ Excel文件导出
✨ 配置文件自动读取