lingui-workflow · git:20260223.f8bb334 · 2026-02-23 · sha256 2fcff477c5b1d7f6
lingui-workflow git:20260223.f8bb334A
Immutable. This exact content never changes and is served at /api/v1/blob/2fcff477c5b1d7f6.
---
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.
---
# 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`，不要混用职责。
## Prerequisites
Before using this skill, confirm your project already has Lingui runtime setup:
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.
## Quick Start
推荐最短日常流程（新增/修改文案）：
```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。
3. `i18n:manifest` 可替代 `i18n:compile`。
实际：manifest 依赖已有 `.mjs`，不会自行生成编译产物。
4. 只在 `[lang]/layout.tsx` 做初始化就够了。
实际：在 Next App Router / RSC 下，服务端 `page.tsx` 也应在使用 `t` 或生成 metadata 前初始化 locale。
## Runtime Locale Error Checklist
遇到以下错误时按顺序检查：
`Lingui: Attempted to call a translation function without setting a locale`
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. 新增/修改文案后，已执行 `extract -> translate -> compile`。
2. `translate` 输出缺失项为预期状态（已补翻或接受占位）。
3. 构建前确认已执行 compile（或 `build` 脚本含 compile gate）。
4. `.gitignore` 已忽略编译产物 `web/src/locales/**/*.js|*.mjs`（及兼容路径）。
## References
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`