git:20260826.c8e2576 to git:20260905.8844a98

32 added, 97 removed. Audit A to A.

---

name: lingui-workflow

- description: Guide daily Lingui command workflow for Next.js and React projects. Use when teams need clear extract/translate/compile/manifest routines, troubleshooting steps, and command semantics for i18n catalogs.

+ description: Choose and troubleshoot extract, translation-check, compile, and catalog-manifest commands in an existing Lingui project. Use for daily catalog maintenance and command semantics, not initial setup, plain text translation, or choosing an i18n library.

metadata:

author: adonis

---

# Lingui Workflow

- ## Agent Behavior

- 当此 skill 被激活时，**先输出以下命令速查表**，再回应用户问题：

- ```

- | 命令 | 作用摘要 | 可用参数 |

- | ----------------- | ---------------------------------------------- | ------------------------------------------------- |

- | i18n:extract | 提取源码文案到 po | — |

- | i18n:translate | 统计缺失翻译 | --fill-source, --strict |

- | i18n:check | 严格翻译检查，缺失即报错退出 | — |

- | i18n:compile | 编译 po → mjs，自动执行 i18n:manifest | — |

- | i18n:manifest | 基于已有 mjs 生成 catalog-manifest.ts | — |

- | i18n:sync | 当前仅等价 i18n:extract | — |

- | i18n:bootstrap | 一次执行 extract + compile(+manifest) | — |

- | i18n | 组合入口；默认 extract + translate | --compile, --fill-source, --no-translate, --strict |

- ```

- ## Overview

- 这个 skill 面向“已经完成 Lingui 接入后的日常使用”，帮助你稳定执行 i18n 命令链路并快速排障。

- 如果你需要的是“初始化/脚手架接入”，请使用 `lingui-next-init`，不要混用职责。

+ 处理已经接入 Lingui 的项目。先回答当前问题或执行已授权的步骤；只有用户要完整速查时才输出命令表。

- ## Prerequisites

+ ## Resolve the Project Contract

- Before using this skill, confirm your project already has Lingui runtime setup:

+ - 复用本轮已确认的项目、包管理器和脚本信息。缺少时先读目标包的 `package.json` 与 Lingui 配置，再按问题查看对应入口；不预先读取所有脚本。

+ - `i18n:*` 是项目自定义名称，不是 Lingui 标准接口。下文示例来自已退役的 `lingui-next-init` 历史模板，仅用于维护既有项目；所有项目以实际脚本为准。不要因缺少 `scripts/i18n`、manifest 或 Next.js SWC 配置就判定普通 React/Lingui 接入不完整。

+ - `@your/web` 是占位符，先替换成已核实的包名；非 workspace 项目在目标包目录运行相应脚本。沿用已有包管理器。

+ - 首次接入不属于本 skill 范围，优先复用用户已选定的项目模板；不要调用已退役的初始化 skill。单纯问命令含义不运行写入命令。

- 1. `scripts/i18n/*` exists (at least `index.ts`, `cli.ts`, `manifest.ts`).

- 2. Next.js SWC plugin contains `["@lingui/swc-plugin", {}]`.

- 3. `src/locales/**` catalogs and `src/i18n/catalog-manifest.ts` flow are already wired.

+ ## Choose the Shortest Relevant Flow

- ## Quick Start

+ - **源码文案改变**：extract → 检查缺失翻译 → 完成翻译后 compile。

+ - **仅修改已有翻译**：检查目标 catalog → compile；没有词条漂移证据就不重复 extract。

+ - **只检查缺失翻译**：已存在的只读严格检查命令，例如 `i18n:check`；不附加 extract、占位回填或 compile。

+ - **只重建 manifest**：确认编译产物已经存在且新鲜，再运行 `i18n:manifest`。

+ - **编译或构建**：先确认 `i18n:compile` / build 是否已包含 manifest 或 compile，避免重复执行。

- 推荐最短日常流程（新增/修改文案）：

+ 采用该历史脚本约定的既有项目，新增源码文案的示例：

```bash

pnpm --filter @your/web run i18n:extract

pnpm --filter @your/web run i18n:translate

pnpm --filter @your/web run i18n:compile

```

- 高频补充命令：

- - 首次初始化：`pnpm --filter @your/web run i18n:bootstrap`

- - 仅重建 manifest：`pnpm --filter @your/web run i18n:manifest`

- - 一条命令串联：`pnpm --filter @your/web run i18n -- --compile`

- - CI / 发布前翻译检查：`pnpm --filter @your/web run i18n:check`

- ## Command Matrix

- | 命令 | 作用摘要 | 可用参数 |

- | ---------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |

- | `i18n:extract` | 提取源码文案到 `po` | — |

- | `i18n:translate` | 统计缺失翻译 | `--fill-source`, `--strict` |

- | `i18n:check` | 严格翻译检查，缺失即报错退出 | — |

- | `i18n:compile` | 编译 `po` 到 `mjs`，并自动执行 `i18n:manifest` | — |

- | `i18n:manifest` | 基于现有 `mjs` 生成 `catalog-manifest.ts` | — |

- | `i18n:sync` | 当前仅等价 `i18n:extract` | — |

- | `i18n:bootstrap` | 一次执行 `extract + compile(+manifest)` | — |

- | `i18n` | 组合入口；默认 `extract + translate`，加 `--compile` 才会编译 | `--compile`, `--fill-source`, `--no-translate`, `--strict` |

- 详细输入/输出/副作用请看 `references/i18n-commands.md`。

- ## Doc Drift Guard

- When command semantics change, docs must be updated in the same change set.

- Trigger files:

- 1. `apps/web/scripts/i18n/index.ts`

- 2. `apps/web/scripts/i18n/manifest.ts`

- 3. `apps/web/scripts/i18n/cli.ts`

- 4. `packages/i18n/src/lingui-config.ts`

- Required doc sync:

- 1. `references/i18n-commands.md`

- 2. `references/workflow-daily.md` (if execution sequence changed)

- 3. `references/maintenance-playbook.md` (if maintenance workflow changed)

- ## Common Misconceptions

- 1. `i18n` 默认会 compile。

- 实际：默认不会，必须显式传 `--compile`。

- 2. `i18n:sync` 是全量同步命令。

- 实际：当前实现仅执行 extract。

+ `i18n:translate` 默认统计缺失，并不调用翻译服务。只有明确接受源文案占位时才用 `--fill-source`，不能把占位回填报告为完成翻译。

- 3. `i18n:manifest` 可替代 `i18n:compile`。

- 实际：manifest 依赖已有 `.mjs`，不会自行生成编译产物。

+ ## Command Semantics and Side Effects

- 4. 只在 `[lang]/layout.tsx` 做初始化就够了。

- 实际：在 Next App Router / RSC 下，服务端 `page.tsx` 也应在使用 `t` 或生成 metadata 前初始化 locale。

+ 需要参数或输入/输出细节时读 [references/i18n-commands.md](references/i18n-commands.md)。需要场景例子时读 [references/workflow-daily.md](references/workflow-daily.md)。不要为一个命令问题同时加载全部参考。

- ## Runtime Locale Error Checklist

+ 仅对经核对仍采用以下历史脚本约定的项目：

- 遇到以下错误时按顺序检查：

+ - `i18n` 默认 extract + translate，显式 `--compile` 才编译；`i18n:sync` 仅 extract。

+ - `i18n:compile` 包含 manifest；`i18n:manifest` 不生成编译 catalog。

+ - `i18n:check` 是只读严格检查。组合入口的 `--strict` 仍会先 extract，不能作为只读检查的替代。

+ - extract 会改写 catalog，并可能清理不再归属的 entry。`I18N_DRY_RUN=1` 只预览清理阶段，**不阻止 extract 写入**；需要只读探测时选只读命令或可丢弃副本。

+ - CLI 失败与“没有缺失翻译”不同。保留实际退出状态；旧脚手架缺少新命令时说明版本差异，不假装执行成功。

- `Lingui: Attempted to call a translation function without setting a locale`

+ ## Diagnose from the Observed Failure

- 1. `initLingui(locale)` 是否执行了 `i18n.activate(locale)`。

- 2. 服务端 `layout.tsx` 与服务端 `page.tsx` 是否都调用了 `initPageLingui(params)`（或等价逻辑）。

- 3. 共享服务端组件中的非 JSX 字符串是否优先使用 `useLingui`/`Trans`，避免依赖全局 `@lingui/core/macro` `t` 的初始化时序。

- 4. `i18n:compile` 后的 manifest 是否包含对应 entry + locale loader。

+ 从失败阶段开始，不固定重跑整个流程：

- ## Daily Checklist

+ 1. 文案未提取：检查对应源码、catalog include/entry 和 extract 结果。

+ 2. 翻译未显示：核对目标 `po`、编译产物与实际 locale loader；有 manifest 的项目再检查它。

+ 3. `Attempted to call a translation function without setting a locale`：先查 locale 初始化与调用顺序，不先修改翻译内容。

+ 4. Next.js App Router / RSC：确认使用翻译的 server layout/page 在调用前完成 locale 初始化；共享服务端组件按已有版本和 `useLingui`/`Trans` 约定取上下文。此项不适用于普通 React 客户端项目。

- 1. 新增/修改文案后，已执行 `extract -> translate -> compile`。

- 2. `translate` 输出缺失项为预期状态（已补翻或接受占位）。

- 3. 构建前确认已执行 compile（或 `build` 脚本含 compile gate）。

- 4. `.gitignore` 已忽略编译产物 `web/src/locales/**/*.js|*.mjs`（及兼容路径）。

+ 运行命令只能证明对应步骤。涉及页面显示时，还需在目标 locale 的真实页面核对文案；没运行就标记 `UNVERIFIED`。

- ## References

+ ## Maintaining These Skills

- 1. `references/i18n-commands.md`

- 2. `references/workflow-daily.md`

- 3. `references/maintenance-playbook.md`

- 4. Runtime implementation check: `apps/web/scripts/i18n/index.ts`

- 5. Runtime implementation check: `apps/web/scripts/i18n/manifest.ts`

+ 仅在修改本仓库 Lingui 工作流文档时读取 [references/maintenance-playbook.md](references/maintenance-playbook.md)。已有项目的命令语义变化经核实后，同步此入口与命令参考；不再维护或同步已退役的初始化模板，也不把仓库维护流程加入下游项目的日常翻译任务。