lingui-framework-setup — Claude Code skill: how to install
lingui-framework-setup configures Lingui i18n for React and Vue frameworks like Next.js, Vite, Remix, or TanStack Start. Prevents SSR locale leaks and compiler macro issues.
MIT 159 installs ★ 12 updated 2026-11-01
npx skills add lingui/skills --skill lingui-framework-setup -a claude-codeWhat lingui-framework-setup does
The skill inspects package.json and build configs before altering files. Every framework handles internationalization differently. The tool distinguishes between Next.js App Router, Pages Router, TanStack Start, React Router 7, Remix v2, Vite SPAs, and Vue 3. It then assigns the right macro transform, choosing between the native Vite plugin, SWC, or Babel.
Lingui 6 is strictly ESM and requires Node 22.19 or Node 24. Projects on older runtimes must pin all Lingui dependencies to version 5. Vite projects import raw .po catalogs directly because the plugin handles compilation on the fly. Next.js lacks this pipeline, so catalog compilation must run explicitly before build and development commands.
The @lingui/detect-locale utility fails under SSR. It reads navigator and localStorage, which throws immediately on the server and ruins hydration. For server-rendered applications, the skill resolves locales from request cookies or Accept-Language headers instead.
What it helps with
- configure the correct macro transform for SWC, Babel, or Vite
- resolve locales in SSR without hydration mismatch or server crashes
- set up
.pocatalog loading for Vite or Next.js pipelines - verify extraction and compilation before running builds
Example prompts for the agent
- Set up Lingui 6 in Next.js App Router with locale-prefixed routes
- Configure Lingui macro transforms in a Vite React application
- Fix Lingui build failures caused by a Vite plugin update
How to install lingui-framework-setup
1Skills CLI (Vercel)
npx skills add lingui/skills --skill lingui-framework-setup -a claude-code2Manually: put the files in place
~/.claude/skills/lingui-framework-setup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/lingui-framework-setup/
1Skills CLI (Vercel)
npx skills add lingui/skills --skill lingui-framework-setup -a codex2Manually: put the files in place
.agents/skills/lingui-framework-setup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add lingui/skills --skill lingui-framework-setup -a cursor2Manually: put the files in place
.cursor/skills/lingui-framework-setup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install lingui/skills skills/lingui-framework-setup2Manually: put the files in place
.github/skills/lingui-framework-setup/SKILL.md1Skills CLI (Vercel)
npx skills add lingui/skills --skill lingui-framework-setup -a gemini-cli2Platform CLI
gemini skills install https://github.com/lingui/skills --path skills/lingui-framework-setupManually: put the files in place
.devin/skills/lingui-framework-setup/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add lingui/skills --skill lingui-framework-setup -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about lingui-framework-setup
How to install lingui-framework-setup in Claude Code?
Run npx skills add lingui/skills --skill lingui-framework-setup -a claude-code.
What does lingui-framework-setup do?
It detects your project framework and compiler configuration to set up Lingui without breaking SSR hydration or macro transformations.
Why should @lingui/detect-locale be avoided in SSR?
It accesses browser globals like window and localStorage, causing server crashes or hydration mismatches. Server-rendered frameworks must extract the locale from cookies or the Accept-Language header.
Source text
SKILL.md · MIT
---
name: lingui-framework-setup
description: Set up Lingui in a React or Vue framework. Use when adding Lingui to a Next.js App Router, Vite, React Router 7, Remix, TanStack Start, or Vue 3 (Vite, Nuxt) project, when wiring locale detection, locale-prefixed URLs, or SSR locale resolution, or when a working setup breaks after a framework or build-tool upgrade.
---
# Lingui Framework Setup
Correct Lingui setup is framework-shaped: what works in a Vite SPA breaks in React Server Components, and a module-level `i18n` singleton that is fine in the browser bleeds locales across requests under SSR. This skill routes to a framework-native recipe instead of a generic `I18nProvider` answer.
**Work in this order: detect the stack → apply the common steps → follow the framework reference → run the verification sequence.**
## Step 1 — Detect the stack
Read `package.json` and the build config before recommending anything. Never guess the compiler — the macro transform silently does nothing when wired into the wrong one.
| Signal | Stack | Reference |
|---|---|---|
| `next` in deps, `app/` or `src/app/` with `layout.tsx` | Next.js App Router | [nextjs-app-router.md](references/nextjs-app-router.md) |
| `next` in deps, `pages/` with `_app.tsx`, no `app/` | Next.js Pages Router | Supported by Lingui, brief notes in [nextjs-app-router.md](references/nextjs-app-router.md) |
| `@tanstack/react-start` in deps | TanStack Start (SSR) | [tanstack-start.md](references/tanstack-start.md) |
| `@react-router/dev` in devDeps + `react-router.config.*` | React Router 7 framework mode (SSR) | [react-router-remix.md](references/react-router-remix.md) |
| `@remix-run/dev` ≥ 2.7 in devDeps + `vite` | Remix v2 (Vite build, SSR) | [react-router-remix.md](references/react-router-remix.md) |
| `vite` + `react`, none of the above | Vite SPA (incl. declarative React Router, TanStack Router) | [vite-spa.md](references/vite-spa.md) |
| `vue` ≥ 3.4 + `@vitejs/plugin-vue` | Vue 3 on Vite (incl. Vue Router) | [vue-vite.md](references/vue-vite.md) |
| `nuxt` in deps | Nuxt (SSR) | Brief notes in [vue-vite.md](references/vue-vite.md) |
Macro transform (decides what to install). On every Vite React stack the default is the **native transform** in `@lingui/vite-plugin` 6.9.1+, whatever the React plugin; the Vite compiler rows are **fallbacks**, and [vite-spa.md](references/vite-spa.md) lists when they apply:
| Signal | Compiler | Macro transform |
|---|---|---|
| Any Vite React stack | none needed | `lingui({ macroTransform: true })` |
| Vue (Vite, Nuxt) | Babel, via `@lingui/vue` | `linguiVue()` from `@lingui/vue/vite` — also compiles `<template>` macros. The native transform doesn't support Vue: never `macroTransform: true` |
| `@vitejs/plugin-react-swc` | SWC | `@lingui/swc-plugin` (pin exactly — see the swc-plugin-compatibility skill) |
| `@vitejs/plugin-react` `^5` or lower | Babel | `@lingui/babel-plugin-lingui-macro` via the plugin's `babel` option |
| `@vitejs/plugin-react` `^6`+, Vite 8 | Babel, standalone pass | v6 removed the `babel` option — run the macro as its own pass: `@rolldown/plugin-babel` + `linguiTransformerBabelPreset()`. Keeps the stock React plugin |
| `@vitejs/plugin-react` `^6`+, Vite ≤ 7 | Babel, standalone pass | Same, via `vite-plugin-babel` (no Rolldown). Switching to `@vitejs/plugin-react-swc` also works, at the cost of an exact pin |
| Next.js, no `.babelrc` | SWC | `@lingui/swc-plugin` via `experimental.swcPlugins` |
| Next.js with `.babelrc` | Babel | `@lingui/babel-plugin-lingui-macro` in `.babelrc` (a Babel config disables Next's SWC) |
One more distinction that changes everything: `react-router` in deps **without** `@react-router/dev` is a declarative SPA (`<Routes>` in JSX) — that is the Vite SPA reference, not the framework-mode one. Route-module `loader`/`+types` code written into a declarative SPA is dead on arrival.
## Step 2 — Common steps (every framework)
**Version gate.** Lingui 6 is current: ESM-only, requires Node ≥ 22.19 (or ≥ 24). Install `@lingui/core@^6 @lingui/react@^6` (Vue: `@lingui/vue@^6`) and dev `@lingui/cli@^6`. If the project cannot meet the Node requirement, pin every `@lingui/*` package to `^5` — do not mix majors. Do not install `@lingui/macro`: since v5 the macros live at `@lingui/react/macro` and `@lingui/core/macro`.
**Per-stack extras** (details in each reference):
| Stack | Extra runtime | Extra dev |
|---|---|---|
| Next.js App Router | — | `@lingui/swc-plugin` (exact pin) |
| Vite SPA | `@lingui/detect-locale` | `@lingui/vite-plugin` (also transforms macros) |
| React Router 7 / Remix | — | `@lingui/vite-plugin` (also transforms macros), `@lingui/format-po` |
| TanStack Start | — | `@lingui/vite-plugin` (also transforms macros) |
| Vue 3 on Vite | `@lingui/detect-locale` | `@lingui/vite-plugin` (catalogs only), `@lingui/extractor-vue`, `@babel/core` |
`@lingui/detect-locale` is browser-only (`navigator`, `localStorage`, `window.location`). Never install it on an SSR stack — it throws on the server or desyncs hydration; SSR stacks resolve locale from the request (cookie / `Accept-Language`) instead.
**Config and catalogs.** Create `lingui.config.ts` with `sourceLocale`, `locales`, and one `catalogs` entry; the lingui-best-practices skill owns catalog hygiene (build-script wiring, gitignore rules, CI drift check) and the single-sourced locale module (`locales.ts` with `resolveLocale`, `getDirection`, `localeDisplayName`) — reuse both, do not re-derive them.
**Two catalog-loading models.** On Vite-based stacks, `@lingui/vite-plugin` compiles `.po` on import — `await import('./locales/en/messages.po')` just works, there are no compiled artifacts to script or gitignore. Next.js has no Vite pipeline: run `lingui compile` prepended to `dev`/`build` scripts and import the compiled catalogs (`@lingui/loader` is webpack-only and Turbopack is the Next 15/16 default, so a loader-based setup is a trap).
## Step 3 — Framework reference
Read the matching reference file fully before editing the project. Every reference follows the same section contract, in order:
**packages → build-tool integration → `lingui.config` → locale resolution → provider/layout wiring → routing strategies → language switcher → gotchas → verification**
If the project needs locale-prefixed URLs, every reference offers the same three strategies — unprefixed source locale, all locales prefixed, or no URL locale (cookie/storage only). Restructuring routes is invasive: ask the user which strategy they want before moving files.
## Step 4 — Verify
Run in this order; each step must pass before the next:
```bash
npx lingui extract --clean # catalogs regenerate; count matches expectations
npx lingui compile # only on stacks with compiled catalogs (Next.js)
npx tsc --noEmit # types resolve, incl. catalog imports (Vue: vue-tsc --noEmit)
npm run build # macro wiring errors surface here
```
**Then prove the transform ran.** A green build does not: a mis-wired macro transform is silently a no-op and the app ships in the source language. Translate one string in a non-source catalog, run the app in that locale, and confirm the translation reaches the browser (each reference gives the stack's exact check — `curl` the server-rendered HTML on SSR stacks, hard-load a deep link on the SPA). The setup is done when you have seen a translated string, not when the build is green.
Raw untranslated text at that point is a compiler wiring problem — wrong plugin, bare-string SWC entry, or the `@vitejs/plugin-react@6` babel trap; see the swc-plugin-compatibility skill. On the native transform, a missing `macroTransform: true` is not silent: the untransformed macro import throws "being executed outside the context of compilation" in the browser.
## Adding a new framework
Another stack (a new meta-framework, a new build tool) costs two edits: one row in the Step 1 detection table, and one file under `references/` following the Step 3 section contract. Framework-specific facts go in the reference; anything true of every stack — the version gate, the two catalog-loading models, the SSR `detect-locale` rule — stays here, stated once. Every non-obvious rule carries a one-sentence why.
## Related skills
- **lingui-best-practices** — macro selection, catalog hygiene, the shared locale module. This skill assumes it; don't duplicate it.
- **swc-plugin-compatibility** — SWC plugin version pinning and the silent-failure modes of a mis-wired transform.
- **migrate-i18next-to-lingui** — if the project already has i18next, migrate first, then return here for framework wiring.
© lingui · MIT · lingui/skills