К основному содержанию
скилл CX Codex

lingui-framework-setup — скилл для Claude Code: установка

Скилл lingui-framework-setup настраивает интернационализацию с Lingui под Next.js, Remix, TanStack Start или Vite. Предотвращает ошибки сборки макросов и утечки локалей на сервере.

MIT 159 установок ★ 12 обновлён 2026-11-01

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add lingui/skills --skill lingui-framework-setup -a claude-code
Открыть на GitHub

Что делает lingui-framework-setup

Скилл проверяет зависимости в package.json и файлы сборки проекта. Подход к интернационализации зависит от стека. Модуль различает Next.js App Router, Pages Router, TanStack Start, React Router 7, Remix v2, обычные SPA на Vite и Vue 3. Для каждого фреймворка подбирается свой трансформ макросов: нативный плагин Vite, SWC или Babel.

Lingui 6 работает как ESM и требует Node.js версии от 22.19. Если окружение не обновлено, зависимости фиксируются на пятой мажорной версии. Смешивать мажорные ветки нельзя. В Vite каталоги переводов .po подключаются напрямую. В Next.js такой сборки на лету нет, поэтому компиляция каталогов запускается заранее перед стартом приложения.

Библиотека @lingui/detect-locale написана строго для браузера. В SSR она моментально уронит сервер из-за отсутствия глобальных объектов window и navigator. На сервере локаль извлекается только из кук или заголовка Accept-Language.

Какие задачи решает

  • выбрать подходящий макрос для SWC, Babel или Vite
  • настроить определение локали в SSR без падения сервера
  • подключить импорт каталогов .po в Next.js или Vite
  • проверить экстракцию сообщений перед сборкой проекта

Примеры запросов агенту

  • Настрой Lingui 6 для Next.js App Router с языковыми префиксами в URL
  • Подключи макросы Lingui в проект на Vite и React
  • Исправь падение сборки Lingui после обновления плагинов Vite

Как установить lingui-framework-setup

1Через Skills CLI (Vercel)

npx skills add lingui/skills --skill lingui-framework-setup -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/lingui-framework-setup/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о lingui-framework-setup

Как установить lingui-framework-setup в Claude Code?

Выполните команду npx skills add lingui/skills --skill lingui-framework-setup -a claude-code.

Что делает скилл lingui-framework-setup?

Анализирует используемый фреймворк и сборщик в проекте, а затем настраивает Lingui без конфликтов гидратации и ошибок компиляции макросов.

Можно ли использовать @lingui/detect-locale в SSR-проектах?

Нет, пакет обращается к объектам window, navigator и localStorage, поэтому на сервере он вызовет ошибку или сбой гидратации. Для серверных проектов локаль извлекают из cookie или заголовка Accept-Language.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
tailwindcss-framework-integration JosiahSiegel Скилл tailwindcss-framework-integration помогает настроить Tailwind CSS в проектах на React, Vite, Next.js, Vue, Nuxt и SvelteKit. Пригодится при подключении плагинов сборщика, тёмной темы и слиянии классов. CX Codex +1 298установок framework-to-capacitor Cap-go Скилл framework-to-capacitor для Claude Code настраивает сборку веб-фреймворка в статический бандл для мобильного приложения на Capacitor. Помогает при переносе проектов Next.js, Nuxt, Angular, SvelteKit и Vite на iOS и Android. CX Codex +1 932установок react-software-architect-review Giuseppe Trisciuoglio Субагент react-software-architect-review для Claude Code разбирает архитектуру React-приложения: компоненты, состояние, поток данных и производительность. Помогает пересмотреть структуру проекта на React 19 или Next.js. CX Codex ★ 372звёзд репо i18n-expert daymade Скилл i18n-expert настраивает и проверяет локализацию интерфейса: заменяет строки ключами, сверяет локали и форматирование. Нужен при работе с React, Next.js или Vue. CX Codex +1 2 800установок internationalization-i18n Mindrally Скилл internationalization-i18n для Claude Code, Codex и Cursor задаёт правила интернационализации в веб- и мобильных проектах. Подключается при настройке перевода приложения на несколько языков. CX Codex +1 1 000установок next-intl-app-router liuchiawei Скилл next-intl-app-router для Claude Code. Настраивает next-intl с локалью в пути: конфиг, прокси, навигация и файлы сообщений. Закрывает добавление второго языка в проект. CX Codex +1 619установок

Из того же набора6

lingui-best-practices Скилл lingui-best-practices помогает внедрять Lingui для локализации интерфейсов и каталогов переводов. Пригодится при добавлении i18n в приложения на React, Vue или JavaScript. CX Codex +1 811установок enhanced-message-context Скилл enhanced-message-context для Claude Code расставляет комментарии для переводчиков в сообщениях Lingui и решает, каким строкам они нужны — двусмысленным подписям и непрозрачным плейсхолдерам вроде {count}. CX Codex +1 630установок swc-plugin-compatibility Скилл swc-plugin-compatibility помогает устранить сбои сборки и несовместимость @lingui/swc-plugin с Next.js, Vite и Rspack, когда макросы локализации не преобразуются. CX Codex +1 305установок migrate-i18next-to-lingui Скилл migrate-i18next-to-lingui для Claude Code переносит проект с i18next и react-i18next на Lingui — от конфигурации до каталогов переводов. Помогает поэтапно заменить API. CX Codex +1 197установок find-unwrapped-strings Скилл find-unwrapped-strings находит пользовательские строки в проекте Lingui, которые не обёрнуты макросами перевода. Запускайте его после настройки или миграции, чтобы проверить, что осталось вне каталогов. CX Codex +1 165установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой