如何使用Excel文件替代JSON文件搭配NestJS-i18n？

核心逻辑 #

NestJS-i18n 默认仅支持 JSON/YAML 格式的翻译源文件，要对接 Excel 管理翻译，核心是将 Excel 内容转换成框架可识别的 JSON 格式，主要分为「Excel 转 JSON 的转换流程」和「NestJS 项目集成逻辑」两个环节。

具体实现步骤 #

1. 统一 Excel 表格结构 #

先规范 Excel 的格式，方便后续解析：

• 第一列固定为翻译键（如 greeting.hello），支持嵌套层级格式
• 后续列对应不同语言，列名使用标准语言代码（如 en、zh-CN、ja）

示例表格结构：

2. 编写 Excel 转 JSON 脚本 #

使用 Node.js 的 xlsx 库读取 Excel 文件，将内容按语言拆分并生成对应 JSON 文件。

示例脚本代码：

const XLSX = require('xlsx');
const fs = require('fs');
const path = require('path');

// 读取目标 Excel 文件
const workbook = XLSX.readFile(path.join(__dirname, '../translations.xlsx'));
const worksheet = workbook.Sheets[workbook.SheetNames[0]];
const rawData = XLSX.utils.sheet_to_json(worksheet);

// 按语言分组生成嵌套结构的 JSON
const langTranslations = {};
rawData.forEach(item => {
  const key = item.key;
  delete item.key;

  Object.keys(item).forEach(lang => {
    if (!langTranslations[lang]) {
      langTranslations[lang] = {};
    }
    // 将点分隔的嵌套键转为嵌套对象
    const keySegments = key.split('.');
    let currentObj = langTranslations[lang];
    keySegments.forEach((seg, idx) => {
      if (idx === keySegments.length - 1) {
        currentObj[seg] = item[lang] || '';
      } else {
        currentObj[seg] = currentObj[seg] || {};
        currentObj = currentObj[seg];
      }
    });
  });
});

// 将生成的 JSON 写入 NestJS-i18n 指定的翻译目录
const outputDir = path.join(__dirname, '../src/i18n');
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true });
}
Object.keys(langTranslations).forEach(lang => {
  fs.writeFileSync(
    path.join(outputDir, `${lang}.json`),
    JSON.stringify(langTranslations[lang], null, 2)
  );
});

3. 集成到项目工作流 #

• 将脚本保存到项目的 scripts 目录下（如 scripts/i18n-convert.js）
• 在 package.json 中添加执行命令，方便快速触发转换：

  "scripts": {
    "i18n:convert": "node scripts/i18n-convert.js"
  }
  

• 日常开发：每次 Excel 翻译内容更新后，执行 npm run i18n:convert 生成最新 JSON 文件
• 生产构建：可将转换命令前置到构建流程中，确保构建时使用最新翻译：

  "scripts": {
    "build": "npm run i18n:convert && nest build"
  }
  

4. 可选：自动监听 Excel 文件变化 #

如果想避免手动执行脚本，可使用 chokidar 库监听 Excel 文件，文件更新时自动触发转换：

const chokidar = require('chokidar');

const watcher = chokidar.watch(path.join(__dirname, '../translations.xlsx'));
watcher.on('change', () => {
  console.log('翻译文件已更新，自动转换中...');
  // 此处复用上述转换逻辑
});

注意事项 #

• 确保 Excel 中的翻译键格式统一，避免嵌套键格式错误（如多写/漏写点分隔符）
• 处理 Excel 中的空值：可给空翻译设置默认语言值或留空，避免 JSON 结构异常
• 给脚本添加错误捕获逻辑，防止转换失败导致项目构建中断

内容的提问来源于stack exchange，提问作者Đoàn Đức Bảo