LinguiJS：移除过时条目时保留手动添加的翻译项

核心原因 #

lingui extract --clean的逻辑是删除所有标记为"obsolete": true的条目，不管这个标记是Lingui自动生成的还是你手动添加的。你手动给条目加obsolete: true等于告诉Lingui这个条目是过时的，所以会被清理掉。

保留手动条目的两种方案 #

方案1：移除手动条目的obsolete标记 #

如果你的手动条目对应的myI18nEntryKey确实在代码中存在（比如i18n._("myI18nEntryKey")），直接去掉"obsolete": true即可：

"myI18nEntryKey": {
    "translation": "my entry value"
}

Lingui会识别到代码中的key，不会把它标记为过时，--clean也不会删除它。

如果这个key不在代码中但你想保留，不要加obsolete标记，而是用下面的方案2单独维护。

方案2：拆分自动/手动条目目录（最优工作流） #

把自动生成和手动维护的条目分开管理，让extract --clean只处理自动生成的部分，手动条目完全不受影响。

步骤1：调整目录结构

创建两个文件分别存放自动和手动条目：

locales/
  en/
    auto.json      # 由lingui extract自动生成、维护
    manual.json    # 手动编写的条目，自己管控
  zh/
    auto.json
    manual.json

步骤2：修改Lingui配置

在lingui.config.js中指定extract只处理auto.json，排除手动文件：

module.exports = {
  locales: ["en", "zh"],
  catalogs: [
    {
      path: "locales/{locale}/auto",
      include: ["src"], // 你的源码目录
      exclude: ["**/node_modules/**"],
    },
  ],
  // 其他原有配置...
};

步骤3：合并条目（二选一）

方式A：构建前合并文件

写个简单的Node脚本合并两个文件，手动条目优先级高于自动（重复key时手动覆盖自动）：

// merge-i18n.js
const fs = require("fs");
const path = require("path");

const locales = ["en", "zh"];

locales.forEach(locale => {
  const autoPath = path.join(__dirname, `locales/${locale}/auto.json`);
  const manualPath = path.join(__dirname, `locales/${locale}/manual.json`);
  const outputPath = path.join(__dirname, `locales/${locale}/messages.json`);

  const autoMessages = fs.existsSync(autoPath) ? JSON.parse(fs.readFileSync(autoPath, "utf8")) : {};
  const manualMessages = fs.existsSync(manualPath) ? JSON.parse(fs.readFileSync(manualPath, "utf8")) : {};

  const merged = { ...autoMessages, ...manualMessages };
  fs.writeFileSync(outputPath, JSON.stringify(merged, null, 2));
});

然后在package.json的scripts里添加命令：

{
  "scripts": {
    "i18n:extract": "lingui extract --clean && node merge-i18n.js",
    "i18n:compile": "lingui compile"
  }
}

方式B：代码中直接合并加载

不用生成合并文件，在初始化Lingui时直接合并两个文件的内容：

import { i18n } from "@lingui/core";
// 加载自动生成的条目
import enAuto from "./locales/en/auto.json";
import zhAuto from "./locales/zh/auto.json";
// 加载手动维护的条目
import enManual from "./locales/en/manual.json";
import zhManual from "./locales/zh/manual.json";

// 合并后加载
i18n.load({
  en: { ...enAuto, ...enManual },
  zh: { ...zhAuto, ...zhManual },
});
i18n.activate("en");

内容的提问来源于stack exchange，提问作者Army Noodles