Next.js 連携

アルファ

Lingo.dev Compiler は現在アルファ版です。動作は安定しておらず、本番環境での利用は推奨されません。API はリリースごとに変更される可能性があります。

Lingo.dev Compiler は、ビルドパイプラインを変換してロケールごとのバンドルを生成する withLingo() 設定ラッパーを通じて、Next.js App Router と統合できます。React Server Components、Webpack、Turbopack に対応しており、コンポーネントコードの変更は必要ありません。

前提条件#

要件

App Router を使用する Next.js 14 以降
Node.js 18 以降
@lingo.dev/compiler がインストール済み

インストール#

bash

pnpm install @lingo.dev/compiler

next.config.ts を設定する#

Next.js の設定を withLingo でラップします。設定関数は async である必要があります。これは、withLingo がビルド時に非同期で初期化を行うためです。

// next.config.ts
import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {
    sourceRoot: "./app",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    models: "lingo.dev",
    dev: {
      usePseudotranslator: true,
    },
  });
}

非同期設定が必要です

設定はプレーンオブジェクトではなく、async 関数としてエクスポートする必要があります。プレーンオブジェクトをエクスポートすると Compiler を初期化できず、ビルドは失敗します。詳しくはトラブルシューティングを参照してください。

LingoProvider を追加する#

コンポーネントツリー全体でロケールコンテキストを有効にするため、ルートレイアウトを LingoProvider でラップしてください。

tsx

// app/layout.tsx
import { LingoProvider } from "@lingo.dev/compiler/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

LingoProvider は、ロケールの解決、永続化、辞書の読み込みを担います。Server Components と Client Components の両方で利用できます。

Server Components と Client Components#

Compiler は、両方のコンポーネントタイプを透過的に処理します。

コンポーネントタイプ	翻訳の仕組み
React Server Components	翻訳はサーバー側でリクエスト時に解決されます。クライアント側の JS オーバーヘッドはありません。
Client Components (`"use client"`)	翻訳はクライアントチャンクにバンドルされます。ロケール切り替えには `useLingoContext()` を利用できます。
共有コンポーネント	どちらのコンテキストでも動作します。Compiler がレンダリング環境を自動で検出します。

tsx

// app/page.tsx - Server Component (default)
export default function Home() {
  return <h1>Welcome to our app</h1>;
  // Renders translated text with zero client JS
}

tsx

// app/components/greeting.tsx - Client Component
"use client";

export function Greeting() {
  return <p>Hello, world</p>;
  // Translations included in client bundle
}

バンドラー対応#

withLingo() ラッパーは、Next.js がサポートする両方のバンドラーで動作します。

バンドラー	対応状況	補足
Webpack	完全対応	デフォルトのバンドラーです。追加の設定は不要です。
Turbopack	完全対応	`next dev --turbopack` で有効化できます。Compiler が Turbopack を自動で検出します。

sourceRoot の設定#

sourceRoot オプションは、翻訳対象のコンポーネントが含まれるディレクトリを Compiler に指定するためのものです。Next.js App Router のプロジェクトでは、通常 ./app を指定します。

{
  sourceRoot: "./app",
}

./app の外にコンポーネントがある場合（共有の components/ ディレクトリなど）は、sourceRoot を共通の親ディレクトリに設定してください。

{
  sourceRoot: ".",
}

sourceRoot の範囲を広げると、スキャン対象のファイル数も増えます。大規模なプロジェクトでは、ビルド時間を短縮するため、できるだけ狭く保つのがおすすめです。あるいは useDirective: true を使い、翻訳が必要なファイルにだけ 'use i18n' を追加する方法もあります。詳しくはプロジェクト構成を参照してください。

次のステップ#