json-dir-to-excel

> 把本地目录中的 JSON 文件一键导出为 Excel，同时支持 横向扁平表 与 竖向国际化表，提供 CommonJS / ESM 双模块格式与命令行工具。

特性

• ✅ 扫描目录（可递归）内所有 JSON 文件，合并导出为单个 Excel
• ✅ 自动扁平化嵌套对象（可选）
• ✅ 竖向排列模式（一行一个 key，多语言分列）专为国际化设计
• ✅ CommonJS & ESM 双规范，零配置按需加载
• ✅ TypeScript 编写，自带类型声明
• ✅ 命令行工具 json2excel 开箱即用

安装

 # 全局安装 CLI
npm i -g json-dir-to-excel
# 本地安装，按需引入
npm i json-dir-to-excel

1. 命令行（推荐）

基本用法

json2excel export -i src/lang -o i18n.xlsx --export-mode vertical -r

完整参数

json2excel export -i <目录> -o <文件> -s <工作表> -m <模式> -r -p <正则>

| 短参 | 长参 | 说明 | 默认值 | | ---- | --------------- | ------------------------------------------------- | --------------- | | -i | --input | 要扫描的目录 | ./json | | -o | --output | 输出 Excel 路径 | ./output.xlsx | | -s | --sheet | 工作表名称 | Data | | -m | --export-mode | horizontal 横向扁平表 / vertical 竖向国际化表 | horizontal | | -r | --recursive | 递归子目录 | false | | -p | --pattern | 文件正则（例 \.lang\.json$） | \.json$ | | -f | --no-flatten | 禁用扁平化 | true |

Excel → JSON（反向模式）

基本用法

json2excel reverse ./translations.xlsx ./locales

指定工作表

json2excel reverse ./translations.xlsx ./locales -s "翻译数据"

完整参数

json2excel reverse <Excel 文件> <输出目录> -s <工作表> -m <模式>

以下是参数说明的 Markdown 表格形式：

| 参数 | 说明 | 默认值 | | ----------------- | --------------------------- | -------- | | Excel 文件 | 输入的 Excel 文件路径 | - | | 输出目录 | JSON 文件输出目录 | - | | -s, --sheet | 工作表名称 | Data | | -m, --export-mode | 导出模式（仅支持 vertical） | vertical |

2. 代码调用（CommonJS）

const { jsonDirToExcel } = require('json-dir-to-excel')

;(async () => {
  await jsonDirToExcel({
    inputDir: 'src/lang',
    outputFile: 'src/lang/i18n.xlsx',
    sheetName: 'I18n',
    exportMode: 'vertical', // 竖向：key | en | zh | ...
    includeSubdirs: true,
    filePattern: /\.lang\.json$/i,
  })
  console.log('✅ Excel 已生成')
})()

3. 代码调用（ESM）

import { jsonDirToExcel } from 'json-dir-to-excel'

await jsonDirToExcel({
  inputDir: 'src/lang',
  outputFile: 'src/lang/i18n.xlsx',
  sheetName: 'I18n',
  exportMode: 'vertical',
  includeSubdirs: true,
  filePattern: /\.lang\.json$/i,
})

导出模式对比

| 模式 | 用途 | 示例列头 | | ------------ | -------- | ---------------------------------------------- | | horizontal | 通用数据 | name, age, address.city, __source_file | | vertical | 国际化 | key, en, zh, fr … |

竖向示例（国际化）

| key | en | zh | | ----------------- | ----------- | ---------- | | locale | en-US | zh-CN | | messages.hello | Hello | 你好 | | messages.cart.add | Add to cart | 加入购物车 |

json2excel export -i ./locales -o ./translations.xlsx -m vertical -r

使用场景

场景 1：国际化项目管理

项目结构

src/
  locales/
    en.json
    zh-CN.json
    ja.json

导出到 Excel（便于翻译）：

json2excel export -i ./src/locales -o ./translations.xlsx -m vertical -r

从 Excel 恢复翻译结果：

json2excel reverse ./translations.xlsx ./src/locales

场景 2：配置文件管理

多环境配置文件：

config/
  dev.json
  prod.json

导出到 Excel（便于批量修改）：

json2excel export -i ./config -o ./config-comparison.xlsx -m horizontal

场景 3：数据迁移和备份

将 JSON 数据导出为 Excel 进行编辑： json2excel export -i ./data -o ./backup.xlsx -r -p ".data.json$"

将编辑后的数据恢复为 JSON： json2excel reverse ./backup.xlsx ./data