Skip to content

Adonis0123/adonis-skills / .agents/skills/lingui-workflow

lingui-workflow

Verified

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.

FileKindSize
SKILL.mdskill md4.4 KB
references/i18n-commands.mdmarkdown9.5 KB
references/maintenance-playbook.mdmarkdown2.7 KB
references/workflow-daily.mdmarkdown3.2 KB

references/i18n-commands.md

View on GitHub
# Lingui i18n 命令说明(中文速查)

本文档保留已退役的 `lingui-next-init` 历史模板的 `i18n:*` 命令说明,用于维护仍采用这些脚本的既有项目,不提供初始化入口。先核对目标项目实际 `package.json` 和入口;不同版本与自定义项目可能不同,实际脚本优先,不能把这些命令当成所有 Lingui 项目的标准接口。

## 先看这个

1. 日常新增/修改文案(推荐):
   `pnpm --filter @your/web run i18n:extract`
   `pnpm --filter @your/web run i18n:translate`
   `pnpm --filter @your/web run i18n:compile`

2. 既有项目一次性补齐产物(仅当该脚本存在时):
   `pnpm --filter @your/web run i18n:bootstrap`

3. 只重建 manifest:
   `pnpm --filter @your/web run i18n:manifest`

4. 一条命令串联(高级用法):
   `pnpm --filter @your/web run i18n -- --compile`

注意:`i18n` 默认不会 compile;只有传 `--compile` 才会执行 compile。`i18n:compile` 已包含 manifest,不再单独重复执行它。只读缺失检查使用 `i18n:check`;组合 `i18n -- --strict` 会先 extract,可能改写 catalog。

## 参数组合速查

1. 标准串联并产出编译结果:
   `pnpm --filter @your/web run i18n -- --compile`

2. 仅提取并编译(跳过 translate 统计):
   `pnpm --filter @your/web run i18n -- --no-translate --compile`

3. 翻译缺失项回填 source 文案:
   `pnpm --filter @your/web run i18n:translate -- --fill-source`

4. 严格翻译检查(发现缺失即失败):
   `pnpm --filter @your/web run i18n -- --strict`

## 8 个历史模板命令的语义(须与项目实现核对)

| 命令             | 实际执行                                                                                               | 主要输入                        | 主要输出                                                                | 副作用                                                                                                                                                                | 典型场景                   |
| ---------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `i18n:extract`   | `lingui extract-experimental` + `cleanOrphanedCatalogs()`                                              | 源码中的 `<Trans>` / `t` 文案   | `src/locales/**/*.po` 更新(必要时刷新 `src/i18n/catalog-manifest.ts`) | 会改写 `po` 文件;自动删除不拥有自身消息的 entry 文件(`.po/.mjs`)并清理空目录(`I18N_DRY_RUN=1` 时仅打印待删除文件/目录);非 dry-run 且发生清理时自动重建 manifest | 文案新增或改动后第一步     |
| `i18n:translate` | 统计目标语言缺失;`--fill-source` 时回填 `msgstr`;`--strict` 时缺失即报错                             | `src/locales/**/*.po`           | 控制台缺失统计                                                          | `--fill-source` 会写回目标语言 `po`                                                                                                                                   | 翻译前检查缺失项;占位回填 |
| `i18n:check`     | `translate.ts --strict`;调用 `translateI18n({ strict: true })`,缺失 `msgstr` 时抛出 Error 并非零退出 | `src/locales/**/*.po`           | 控制台缺失统计;缺失时非零退出                                          | 只读,不修改文件                                                                                                                                                      | CI 管线中的翻译完整性门禁  |
| `i18n:compile`   | `lingui compile` 后自动执行 `i18n:manifest`                                                            | `src/locales/**/*.po`           | `src/locales/**/*.mjs` + `src/i18n/catalog-manifest.ts`                 | 会生成/覆盖编译产物与 manifest                                                                                                                                        | 翻译完成后用于运行与构建   |
| `i18n:manifest`  | 仅运行 `scripts/i18n/manifest.ts`                                                                      | 已存在的 `src/locales/**/*.mjs` | `src/i18n/catalog-manifest.ts`                                          | 会覆盖 manifest 文件                                                                                                                                                  | 只想重建 loader 映射时     |
| `i18n:sync`      | 当前仅调用 extract                                                                                     | 源码文案                        | `src/locales/**/*.po` 更新                                              | 行为等价 `i18n:extract`                                                                                                                                               | 兼容入口(不是全流程同步) |
| `i18n:bootstrap` | `extract + compile(+manifest)`                                                                         | 源码文案 + `po`                 | `po/mjs/manifest` 全链路更新                                            | 会执行多步写入                                                                                                                                                        | 既有项目一次性补齐产物     |
| `i18n`           | 组合入口:默认 `extract + translate`;可加 `--compile`、`--fill-source`、`--no-translate`、`--strict`  | 源码文案 + `po`                 | 默认输出统计;可选生成 `mjs/manifest`;`--strict` 时可非零退出          | 取决于参数                                                                                                                                                            | 本地串联流程,减少多条命令 |

`I18N_DRY_RUN=1` 只阻止清理阶段删除文件;extract 命令仍会运行并可能改写 `.po`。它不是整个命令链的只读模式。

## `.gitignore` 建议(编译产物)

建议忽略以下编译产物,避免提交运行时生成文件:

```gitignore
web/src/locales/**/*.js
web/src/locales/**/*.mjs
web/locale/**/*.js
web/locale/**/*.mjs
```

说明:

1. 常用目录是 `web/src/locales/**`,`web/locale/**` 作为兼容路径一并忽略。
2. 这些规则只忽略编译产物,不影响 `po` 源文件提交。

## 常见误用与纠正

1. 误用:以为 `i18n` 默认会 compile。  
   纠正:默认不会,需显式加 `--compile`。

2. 误用:把 `i18n:sync` 当成“全量同步”。  
   纠正:当前实现只做 extract。

3. 误用:只跑 `i18n:manifest` 就想得到最新翻译。  
   纠正:manifest 依赖已编译的 `.mjs`;先 compile 再谈 manifest。

4. 误用:只在 layout 初始化 locale,page 和共享服务端组件不处理。  
   纠正:App Router / RSC 下应确保服务端 layout + page 都完成 locale 初始化(如 `initPageLingui(params)`);共享服务端组件优先 `useLingui`/`Trans`。

## 变更后校验清单(命令语义有改动时)

仅当目标项目仍采用下列历史实现时,按本次改动选择对应检查;路径和行为以目标项目为准,不要求同步已退役模板:

1. 文档同步:

- 更新本文件命令矩阵与参数组合。
- 如流程变化,更新 `references/workflow-daily.md`。

2. 运行校验:

```bash
pnpm --filter @your/web run i18n:extract
pnpm --filter @your/web run i18n -- --strict
pnpm --filter @your/web run i18n:compile
pnpm --filter @your/web run typecheck
```

3. 结果核对:

- `src/i18n/catalog-manifest.ts` 有预期 entry。
- `src/locales/**/*.mjs` 与 `po` 输入一致更新。
- `lingui-config.ts` 中 entries 使用精确两层 glob 自动发现(`src/components/*.tsx` + `src/components/layout/*.tsx`),在覆盖的两个层级内新增可翻译组件无需手动添加路径。
- `manifest.ts` 与 `index.ts` 均通过 `resolveSourceLocale()` 读取 `lingui.config.ts` 的 `sourceLocale`;若配置缺失/非法,按 `DEFAULT_LOCALE -> en` 兼容回退并打印 warning。
- manifest 生成阶段自动跳过不拥有自身消息的 entry(空 catalog 及纯包装组件),无需手动维护排除列表。跳过判据:entry 的 `.po` 中无任何 `#:` 源引用指向 entry 自身源文件(支持后缀:`.ts/.tsx/.js/.jsx/.mts/.cts/.mjs/.cjs/.md/.mdx`)。
- `extractI18n()` 在 `lingui extract-experimental` 之后自动调用 `cleanOrphanedCatalogs(sourceLocale)`;默认删除空 catalog 和纯包装组件 entry 的 `.po/.mjs` 文件并清理空目录。设置 `I18N_DRY_RUN=1` 时只打印待删除文件与空目录用于安全检查;非 dry-run 且发生清理时自动调用 `manifestI18n()`,避免 manifest 仍引用已删除 `.mjs`。

## 历史实现位置示例(实际项目路径优先)

1. 组合逻辑:`web/scripts/i18n/index.ts`
2. 组合入口参数:`web/scripts/i18n/cli.ts`
3. 仅 extract 的 sync 入口:`web/scripts/i18n/sync.ts`
4. extract + compile 的 bootstrap 入口:`web/scripts/i18n/bootstrap.ts`
5. manifest 生成器:`web/scripts/i18n/manifest.ts`
6. translate / check 逻辑:`web/scripts/i18n/translate.ts`(`i18n:check` = `translate.ts --strict`)
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall