Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add lingui/skills --skill lingui-framework-setup -a claude-code
Open on GitHub

What 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 .po catalog 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-code

2Manually: put the files in place

~/.claude/skills/lingui-framework-setup/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/lingui-framework-setup/

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

Similar skills

All skills for Frontend and UI →
tailwindcss-framework-integration JosiahSiegel tailwindcss-framework-integration guides Tailwind CSS setup across React, Vite, Next.js, Vue, Nuxt, and SvelteKit. Useful for configuring bundler plugins, dark mode, and framework class merging. CX Codex +1 298installs framework-to-capacitor Cap-go framework-to-capacitor is a Claude Code skill that configures static web builds for Capacitor when preparing Next.js, Nuxt, Angular, SvelteKit, or Vite projects for iOS and Android. CX Codex +1 932installs react-software-architect-review Giuseppe Trisciuoglio react-software-architect-review audits React architecture: how components compose, where state lives, how data flows, what costs render time. Useful once a React 19 or Next.js codebase has grown past its first structure. CX Codex ★ 372repo stars i18n-expert daymade i18n-expert sets up and audits UI localization by replacing visible strings with keys and checking locale parity. Use it for React, Next.js, or Vue codebases. CX Codex +1 2,800installs internationalization-i18n Mindrally internationalization-i18n — a skill for Claude Code, Codex and Cursor that sets internationalization rules for web and mobile projects. It guides an agent through extracting strings, locale formatting and RTL layouts. CX Codex +1 1,000installs next-intl-app-router liuchiawei next-intl-app-router sets up next-intl with locale-prefixed routes: config, proxy, navigation and message files. Useful when a project gets a second language. CX Codex +1 619installs

From the same set6

Project sponsors

Companies that keep this analytics open