i18n文件与Excel双向转换工具

一个用于在 JavaScript/TypeScript/JSON 格式的 i18n 国际化文件与 Excel 表格之间进行双向转换的命令行工具。

功能特性

• 🔄 支持 i18n 文件 与 Excel 的双向转换（JS -> Excel，Excel -> JS/TS/JSON）
• 🚀 支持多个 i18n 文件同时转换为 Excel
• 📊 自动将嵌套对象展开为 JSON 数组格式的键路径（如 ["user","profile","name"]），避免点号与特殊字符歧义
• 📁 支持自定义输出路径与输出目录
• 🧩 Excel -> JS/TS/JSON 时可自定义扩展名（js|ts|json）
• ✏️ JS/TS 输出为 ESM 默认导出，JSON 输出为纯对象
• ✅ 完整的错误处理和验证
• 🎨 美观的命令行界面和进度显示
• 📈 详细的处理统计信息
• 🛡️ 默认覆盖输出文件，可通过 --no-overwrite 禁止覆盖

环境要求

• Node.js: >= 12.0.0
• npm: >= 6.0.0（通常随 Node.js 一起安装）

安装

# 全局安装
npm install -g i18n-to-xlsx

# 或在项目中本地安装
npm install i18n-to-xlsx

使用方法

JS/TS -> Excel（从多个 .js/.ts 文件生成 .xlsx）

# 转换单个 JavaScript 文件
i18n-to-xlsx ./locales/en.js

# 转换单个 TypeScript 文件
i18n-to-xlsx ./locales/en.ts

# 转换多个文件（支持混合 .js 和 .ts）
i18n-to-xlsx ./locales/en.js ./locales/zh.ts ./locales/fr.js

# 转换多个 TypeScript 文件
i18n-to-xlsx ./locales/en.ts ./locales/zh.ts ./locales/fr.ts

指定输出路径

# 自定义输出文件路径（支持 .js 和 .ts 文件）
i18n-to-xlsx ./locales/en.js ./locales/zh.ts -o ./output/i18n-data.xlsx

Excel -> JS/TS/JSON（从单个 .xlsx 生成多个 i18n 文件）

# 从 Excel 生成 JS 文件（默认覆盖已存在文件）
i18n-to-xlsx ./output/i18n-data.xlsx --out-dir ./locales --ext js

# 从 Excel 生成 TS 文件（默认覆盖已存在文件）
i18n-to-xlsx ./output/i18n-data.xlsx --out-dir ./locales --ext ts

# 从 Excel 生成 JSON 文件（默认覆盖已存在文件）
i18n-to-xlsx ./output/i18n-data.xlsx --out-dir ./locales --ext json

# 如需保留已存在文件，请使用 --no-overwrite
i18n-to-xlsx ./output/i18n-data.xlsx --out-dir ./locales --ext js --no-overwrite

显示详细信息

# 显示详细的处理过程（支持 .js 和 .ts 文件）
i18n-to-xlsx ./locales/en.js ./locales/zh.ts --verbose

查看帮助与版本

# 显示帮助信息
i18n-to-xlsx --help

# 显示版本信息
i18n-to-xlsx --version

支持的文件格式

输入文件格式

• JavaScript 文件（.js）：文件需导出默认对象（仅支持 ESM）
• TypeScript 文件（.ts）：文件需导出默认对象（仅支持 ESM），自动剥离类型注解
• Excel 文件（.xlsx）：第一行为表头，包含 Key 与各语言文件列

ESM 支持说明

工具可解析包含 import 的 ESM 文件，会使用 esbuild 对源码及相对/第三方依赖进行打包后再解析：

• JavaScript 文件：使用 js 加载器进行解析
• TypeScript 文件：使用 ts 加载器进行解析，自动处理类型注解、接口定义、枚举等 TypeScript 特性
• 请尽量避免动态 import/require、运行期副作用（例如在模块顶层进行网络请求或文件写入）
• 确保默认导出为纯对象

输出文件格式

• JavaScript / TypeScript / JSON 文件（.js / .ts / .json）

输出格式

生成的 Excel 文件包含：

1. 主数据表（工作表名：i18n数据）：

   • 第一列：Key 路径（JSON 数组字符串，如 ["common","save"]、["user","profile"]）
   • 其他列：各语言文件对应的翻译值（列名为文件名）

2. 元数据表（工作表名：元数据，可选）：

   • 生成时间、源文件信息、统计数据

Excel -> JS/TS/JSON 时的输出：

• JS/TS 文件：export default { ... }（ESM 默认导出对象）
• JSON 文件：{ ... }（纯对象内容，无导出语句）

示例

JS/TS -> Excel 示例

假设有以下 i18n 文件：

en.js

export default {
  common: {
    save: 'Save',
    cancel: 'Cancel'
  },
  user: {
    profile: 'Profile'
  }
};

zh.ts

interface I18nData {
  common: {
    save: string;
    cancel: string;
  };
  user: {
    profile: string;
  };
}

const zhData: I18nData = {
  common: {
    save: '保存',
    cancel: '取消'
  },
  user: {
    profile: '个人资料'
  }
};

export default zhData;

运行命令：

i18n-to-xlsx en.js zh.ts

生成的 Excel 表格将包含：

| Key | en | zh | |-----|----|----| | ["common","save"] | Save | 保存 | | ["common","cancel"] | Cancel | 取消 | | ["user","profile"] | Profile | 个人资料 |

Excel -> JS/TS/JSON 示例

当 Excel 中主数据表（i18n数据）的第一行是表头，例如：

| Key | en | zh | |-----|----|----| | ["common","save"] | Save | 保存 | | ["common","cancel"] | Cancel | 取消 |

运行命令：

i18n-to-xlsx ./output/i18n-data.xlsx --out-dir ./locales --ext js

将生成：

• ./locales/en.js（内容：export default { common: { save: 'Save', cancel: 'Cancel' } }）
• ./locales/zh.js（内容：export default { common: { save: '保存', cancel: '取消' } }）

开发

项目结构

src/
├── types.ts          # TypeScript 类型定义
├── fileParser.ts     # 文件解析模块
├── dataTransformer.ts # 数据转换模块
├── excelGenerator.ts # Excel 生成模块
├── cli.ts           # 命令行接口
└── index.ts         # 主入口文件

开发命令

# 编译 TypeScript
npm run build

# 清理编译文件
npm run clean

# 代码类型检查（不生成输出）
npm run check

# 运行测试
npm test

# 监听测试（交互式）
npm run test:watch

# 生成测试覆盖率报告
npm run test:coverage

# 示例：JS -> Excel
npm run i18n-to-xlsx

# 示例：Excel -> JS（输出文件位于 package.json 的 temp 路径示例，可按需调整）
npm run excel-to-i18n

错误处理

工具提供完整的错误处理，包括：

• 文件不存在
• 不支持的文件格式（例如输入既不是多个 .js/.ts，也不是单个 .xlsx）
• 文件内容不是有效对象 / Excel 数据格式无效
• TypeScript 类型错误或语法错误
• 输出路径无效 / 输出目录不可写
• 权限问题

每个错误都会提供详细的错误信息和解决建议。

许可证

MIT License

发布与发版

• 预发布检查（运行测试并构建）：

  • npm run preversion

• 发版（默认补丁版本）：

  • npm run release

• 发版（补丁/次要/主要版本）：

  • npm run release:patch
  • npm run release:minor
  • npm run release:major

• 发布到 npm（在发版命令中已包含 npm publish）：

  • 如需仅发布（跳过版本号变化），可使用：
    • npm run build && npm publish

说明：

• prepublishOnly 会在执行 npm publish 前自动构建，确保 dist 产物最新。
• 所有 release:* 命令都会先运行测试与构建，确保质量。
• 提交信息格式为 chore(release): <version>，便于生成变更日志。