lingui-framework-setup

Lingui フレームワークのセットアップ

Lingui の適切なセットアップは、フレームワークごとに異なります。Vite SPA で動作する方法が React Server Components では機能しないことがあり、ブラウザーでは問題のないモジュールレベルの i18n シングルトンも、SSR ではリクエスト間でロケールが漏れてしまいます。このスキルでは、汎用的な I18nProvider の回答ではなく、フレームワークに適したレシピを案内します。

次の順序で作業してください：スタックを検出 → 共通手順を適用 → フレームワークのリファレンスに従う → 検証手順を実行。

ステップ 1 — スタックを検出する

何かを推奨する前に、package.json とビルド設定を確認してください。コンパイラーを決めつけてはいけません。誤ったコンパイラーに設定すると、マクロ変換が何もせずに終わります。

シグナル	スタック	リファレンス
依存関係に next があり、layout.tsx を含む app/ または src/app/ がある	Next.js App Router	nextjs-app-router.md
依存関係に next があり、_app.tsx を含む pages/ があり、app/ はない	Next.js Pages Router	Lingui でサポートされています。nextjs-app-router.md に簡単な説明があります
依存関係に @tanstack/react-start がある	TanStack Start（SSR）	tanstack-start.md
devDeps に @react-router/dev があり、react-router.config.* がある	React Router 7 のフレームワークモード（SSR）	react-router-remix.md
devDeps に @remix-run/dev ≥ 2.7 があり、vite がある	Remix v2（Vite ビルド、SSR）	react-router-remix.md
vite と react があり、上記のいずれにも該当しない	Vite SPA（宣言的な React Router、TanStack Router を含む）	vite-spa.md

マクロ変換（インストールするものを決定します）。すべての Vite スタックでは、React プラグインにかかわらず、既定で @lingui/vite-plugin 6.9.1+ のネイティブ変換を使用します。Vite コンパイラーの各行はフォールバックであり、適用条件は vite-spa.md に記載されています。

シグナル	コンパイラー	マクロ変換
すべての Vite スタック	不要	lingui({ macroTransform: true })
@vitejs/plugin-react-swc	SWC	@lingui/swc-plugin（厳密にバージョンを固定してください。swc-plugin-compatibility スキルを参照）
@vitejs/plugin-react ^5 以下	Babel	プラグインの babel オプションを使った @lingui/babel-plugin-lingui-macro
@vitejs/plugin-react ^6 以上、Vite 8	Babel、スタンドアロンパス	v6 では babel オプションが削除されました。マクロを独立したパスとして実行してください：@rolldown/plugin-babel + linguiTransformerBabelPreset()。標準の React プラグインはそのまま使用します
@vitejs/plugin-react ^6 以上、Vite ≤ 7	Babel、スタンドアロンパス	同じ方法を vite-plugin-babel（Rolldown なし）で使用します。@vitejs/plugin-react-swc に切り替える方法もありますが、その場合はバージョンを厳密に固定する必要があります
Next.js、.babelrc なし	SWC	experimental.swcPlugins 経由の @lingui/swc-plugin
.babelrc がある Next.js	Babel	.babelrc 内の @lingui/babel-plugin-lingui-macro（Babel の設定を行うと Next の SWC は無効になります）

さらに、すべてを左右する違いがもう 1 つあります。依存関係に react-router があり、@react-router/dev がない場合は、宣言的な SPA（JSX 内の <Routes>）です。これは Vite SPA のリファレンスに従い、フレームワークモードのリファレンスには従いません。宣言的な SPA にルートモジュールの loader／+types コードを書いても、最初から動作しません。

ステップ 2 — 共通手順（すべてのフレームワーク）

バージョン要件。 現行バージョンは Lingui 6 です。ESM のみで、Node ≥ 22.19（または ≥ 24）が必要です。@lingui/core@^6 @lingui/react@^6 と、開発用の @lingui/cli@^6 をインストールしてください。プロジェクトが Node の要件を満たせない場合は、すべての @lingui/* パッケージを ^5 に固定してください。メジャーバージョンを混在させないでください。@lingui/macro はインストールしないでください。v5 以降、マクロは @lingui/react/macro と @lingui/core/macro に含まれています。

スタックごとの追加パッケージ（詳細は各リファレンスを参照してください）。

スタック	実行時の追加パッケージ	開発時の追加パッケージ
Next.js App Router	—	@lingui/swc-plugin（厳密にバージョンを固定）
Vite SPA	@lingui/detect-locale	@lingui/vite-plugin（マクロの変換も行います）
React Router 7 / Remix	—	@lingui/vite-plugin（マクロの変換も行います）、@lingui/format-po
TanStack Start	—	@lingui/vite-plugin（マクロの変換も行います）

@lingui/detect-locale はブラウザー専用です（navigator、localStorage、window.location を使用します）。SSR スタックには絶対にインストールしないでください。サーバー上でエラーになるか、ハイドレーションが不整合を起こします。SSR スタックでは代わりに、リクエストからロケールを解決します（cookie / Accept-Language）。

設定とカタログ。 sourceLocale、locales、1 つの catalogs エントリーを含む lingui.config.ts を作成してください。カタログの整備（ビルドスクリプトの連携、gitignore のルール、CI での差分チェック）と、ロケールモジュールの単一情報源（resolveLocale、getDirection、localeDisplayName を含む locales.ts）は lingui-best-practices スキルが担います。両方を再利用し、独自に作り直さないでください。

2 つのカタログ読み込みモデル。 Vite ベースのスタックでは、@lingui/vite-plugin が .po をインポート時にコンパイルするため、await import('./locales/en/messages.po') だけで動作します。スクリプトで処理したり gitignore に追加したりするコンパイル済み成果物はありません。Next.js には Vite のパイプラインがないため、dev / build スクリプトの先頭に lingui compile を追加し、コンパイル済みカタログをインポートしてください（@lingui/loader は webpack 専用であり、Next 15/16 のデフォルトは Turbopack なので、ローダーベースの設定は落とし穴になります）。

ステップ 3 — フレームワークリファレンス

プロジェクトを編集する前に、該当するリファレンスファイルを最初から最後まで読んでください。すべてのリファレンスは、次のセクション構成と順序に従います。

パッケージ → ビルドツールとの連携 → lingui.config → ロケールの解決 → プロバイダー／レイアウトの設定 → ルーティング戦略 → 言語切り替え機能 → 注意点 → 検証

ロケールのプレフィックス付き URL が必要な場合、すべてのリファレンスで同じ 3 つの戦略を提示しています。ソースロケールにはプレフィックスを付けない、すべてのロケールにプレフィックスを付ける、URL にロケールを含めない（cookie / storage のみ）です。ルートの再構成は影響が大きいため、ファイルを移動する前に、どの戦略にするかユーザーに確認してください。

ステップ 4 — 検証

次の順序で実行してください。各ステップに合格してから次に進んでください。

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
npm run build                # macro wiring errors surface here

続いて、変換が実行されたことを確認してください。 ビルドが成功しても、それだけでは証明になりません。マクロ変換の設定に不備があると、何も起きないままアプリがソース言語で公開されてしまいます。ソース以外のカタログで文字列を 1 つ翻訳し、そのロケールでアプリを実行して、翻訳がブラウザーに届くことを確認してください（各リファレンスには、スタックごとの具体的な確認方法が記載されています。SSR スタックではサーバーがレンダリングした HTML に curl を実行し、SPA ではディープリンクを直接読み込みます）。翻訳済みの文字列を実際に確認できた時点で、設定は完了です。ビルドに成功しただけでは完了ではありません。

この時点で未翻訳のテキストがそのまま表示される場合は、コンパイラーの連携に問題があります。プラグインの誤り、SWC のエントリーが文字列のみ、または @vitejs/plugin-react@6 の babel に関する落とし穴などが考えられます。swc-plugin-compatibility スキルを参照してください。ネイティブ変換で macroTransform: true が指定されていない場合は、何も起きないわけではありません。変換されていないマクロのインポートは、ブラウザーで "being executed outside the context of compilation" というエラーを発生させます。

新しいフレームワークの追加

別のスタック（新しいメタフレームワーク、新しいビルドツール）の追加には、2 か所の編集が必要です。ステップ 1 の検出テーブルに行を 1 つ追加し、ステップ 3 のセクション構成に従ったファイルを references/ の下に 1 つ追加します。フレームワーク固有の情報はリファレンスに記載してください。すべてのスタックに当てはまる内容（バージョン要件、2 つのカタログ読み込みモデル、SSR での detect-locale のルール）は、ここに一度だけ記載してください。自明でないルールには、それぞれ理由を 1 文添えてください。

関連スキル

• lingui-best-practices — マクロの選択、カタログの管理、共有ロケールモジュールについて説明します。このスキルはこれを前提としているため、内容を重複させないでください。
• swc-plugin-compatibility — SWC プラグインのバージョン固定と、トランスフォームの配線ミスによるサイレント障害について説明します。
• migrate-i18next-to-lingui — プロジェクトですでに i18next を使用している場合は、先に移行してから、フレームワークの配線についてこのスキルに戻ってください。