---
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`

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`