Next.jsのアプリルーターを使ったアプリケーションを翻訳する

すべてのページをロケールのプレフィックス付きで配信し、プレフィックスのないパスをリダイレクト。@lingo.dev/react-nextで、翻訳済みのサーバーコンポーネントとクライアントコンポーネントをレンダリングします。

アプリルーターでは、ソースロケールを含むすべてのロケールに専用のURLプレフィックスがあり、閲覧者は/en/pricingや/de/pricingにアクセスします。@lingo.dev/react-nextはapp/[locale]ルートセグメントからロケールを読み取り、対応するカタログをサーバーで読み込んで、サーバーコンポーネントとクライアントコンポーネントに同じメッセージを提供します。この手順では、英語のアプリケーションにドイツ語とフランス語を追加します。

Next.js 16以降とReact 19を使用してください。各エントリーはnext/root-paramsを通じてロケールを読み取ります。まず、パッケージをインストールします。

sh
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latest

ロケールを定義する #

app/と同じ階層にi18n.tsを作成します(アプリケーションでsrc/を使用している場合はsrc/i18n.ts)。

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";

export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });

export const localePath = (pathname: string, locale: string) =>
  locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);

.lingo/config.jsonにロケールを列挙し、ソースロケールをdefaultLocaleに指定します。excludeには、app/api/配下のルートハンドラーなど、プレフィックスを付けないパスの先頭セグメントを指定します。slugsは渡さないでください。各ロケールのURLセグメントには、ロケールタグを小文字にしたもの(pt-BRの場合は/pt-br)を使う必要があります。getLingo()がセグメントだけからロケールを判定するためです。独自のスラッグを使うと、プロバイダーはそのスラッグを示すエラーをスローします。プロキシ、サーバーコンポーネント、クライアントコンポーネントのすべてがこのファイルをインポートするため、このファイルにはほかのインポートを追加しないでください。

プレフィックスのないパスをリダイレクトする #

app/と同じ階層にproxy.tsを作成します。

ts
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";

export const proxy = lingoProxy(locales);

export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };

lingoProxy(locales)は、次の2種類のリクエストを処理します。

リクエストレスポンス
/DE/about、/de-AT、/de_DEなど、先頭セグメントがスラッグ以外の形式でロケールを表すパス正規のアドレスへ301。
/aboutなど、ローカライズ対象でありながらロケールが付いていないパスAccept-Languageから決定したロケールへ、Cache-Control: private, no-storeとVary: Accept-Languageを伴う307。
それ以外undefined。

リダイレクトでは、クエリ文字列とアプリケーションのbasePathが維持されます。Next.jsはビルド時にマッチャーを読み取るため、リテラルで記述し、そのapiをexcludeと一致させてください。アプリケーションにすでにプロキシがある場合は、最初にlingoProxyを呼び出し、undefinedが返されたら独自の処理を続けます。middleware.tsは、同じファイルの旧名称です。ファイル名をproxy.tsに、関数名をproxyに変更してください。

ルートをロケール配下に移動する #

ルートレイアウトとすべてのページを、1階層下のapp/[locale]/に移動します。app/[locale]/layout.tsxがルートレイアウトになり、移動後はapp/layout.tsxがなくなります。app/api/配下のルートハンドラー、globals.css、アイコン、robots.ts、sitemap.tsは元の場所に残します。next.configにi18nキーがある場合は削除してください。アプリルーターはこのキーを読み取りません。

tsx
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";

export function generateStaticParams() {
  return lingoStaticParams(locales);
}

export default async function RootLayout({ children }: { children: ReactNode }) {
  const l = await getLingo();
  return (
    <html lang={l.locale} dir={l.direction}>
      <body>
        <LingoAppProvider locales={locales}>{children}</LingoAppProvider>
      </body>
    </html>
  );
}

lingoStaticParamsはロケールごとに1つの{ locale }を返すため、ビルド時にすべてのページがロケールごとに1回ずつ事前レンダリングされます。LingoAppProviderは一覧にないロケールに対して404を返します。export const dynamicParams = falseは追加しないでください。cacheComponentsが有効な場合、Next.jsはこれを受け付けません。

サーバーコンポーネントとクライアントコンポーネントを翻訳する #

サーバーコンポーネント、ページ、レイアウト、generateMetadataでは、@lingo.dev/react-next/app/serverのawait getLingo()を呼び出します。クライアントコンポーネントでは、@lingo.dev/reactのuseLingo()を呼び出します。クライアントコンポーネントのロケールとカタログはLingoAppProviderが提供します。どちらも、ロケールを受け渡す必要はありません。

tsx
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";

export default async function Home() {
  const l = await getLingo();
  return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}

サーバーコンポーネントは、親のサーバーコンポーネントからlをプロパティとして受け取れます。ただし、lをクライアントコンポーネントに渡してはいけません。関数はサーバーからクライアントへ渡せないためです。app/[locale]/の外でgetLingo()を呼び出すと、[locale]セグメントが見つからず、エラーがスローされます。

メタデータを追加する #

tsx
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";

export async function generateMetadata() {
  const l = await getLingo();
  return {
    title: l.text("Pricing", { context: "Title of the pricing page" }),
    ...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
  };
}

lingoMetadata({ locales, pathname, origin, ogLocale? })は、alternates.canonical、各ロケールのalternates.languagesにx-defaultを加えたもの、およびopenGraph.urlとopenGraph.localeを返します。ページのパスは、ロケールのプレフィックス、クエリ、ハッシュを除いて渡してください。動的ルートでは、パラメーターからパスを組み立てます。例にあるオリジンは、自分のサイトのオリジンに置き換えてください。値を生成するlingoHeadと、ogLocaleによる上書きについては、ロケールのURLポリシーで説明しています。

i18n.tsのlocalePath("/pricing", l.locale)を使って、すべての内部リンクにプレフィックスを付けてください。l.localeは通常の文字列なので、localePathでルーターのロケールのいずれかに型を絞り込んでから、locales.prefixでプレフィックスを追加します。プレフィックスのないリンクはプロキシに到達し、ページの言語ではなくブラウザーの言語へリダイレクトされます。redirect()、router.push()、パスを指定するフォームアクションにも同じことが当てはまります。

tsx
"use client";

import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";

export function LocaleSwitcher() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </Link>
      ))}
    </nav>
  );
}

useLocaleSwitch(locales)はロケールごとに1つの{ locale, label, href, current }を返します。これには、そのロケールでの現在のページ、その言語で表記された言語名、現在選択されているロケールかどうかが含まれます。クエリ文字列はハイドレーション後に追加されるため、言語切り替えを表示するページも静的なままです。リンクをたどるとレイアウトが再レンダリングされ、新しいロケールのカタログが読み込まれます。

カタログを抽出して読み込む #

サーバーはfsを使い、nextの実行元フォルダーからlocales/<locale>.jsoncを読み取るため、i18n.messagesPathは既定値のlocalesのままにしてください。参照されなくなったエントリーは除外され、リクエストごとにファイルが読み直されるため、next devは編集後のカタログを次のリクエストで配信します。ファイルがない場合は空のカタログが使われ、開発環境では警告が表示されます。ファイルの形式が不正な場合や、文字列以外の値が含まれる場合は、ファイル名を示すエラーがスローされます。本番環境では、ソースロケールのテキスト自体がフォールバックになるため、そのカタログはブラウザーに送信されません。

app/がプロジェクトのルートにあり、src/フォルダーがない場合は、.lingo/config.jsonで"i18n": { "src": "." }を設定し、抽出時にapp/とcomponents/を走査するようにします。抽出では、node_modulesと、.nextなどのドットで始まるフォルダーはスキップされます。新しく設定する場合は、次を実行します。

sh
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

initはi18nセクションを書き換えるため、実行後にi18n.srcを設定してください。モノレポでは.lingo/config.jsonをリポジトリのルートに置き、パスもそこを起点にします。そのため、messagesPathにはapps/web/localesのように、アプリのフォルダーにlocalesを加えたパスを指定します。CLIの設定にある、名前付きアプリのi18nマップを参照してください。サーバーは引き続き、アプリ自体のフォルダーにあるlocales/を読み取ります。

next buildとnext startの実行後、/を開き、ロケール付きのパスへリダイレクトされることを確認します。続いて/deを開き、HTML内のドイツ語のテキストを確認します。

ランタイム #

事前レンダリングされたページは、どのホストでも動作します。オンデマンドでレンダリングされるページはディスクからカタログを読み取るため、Node.jsランタイムが必要です。Cloudflare Workersとエッジランタイムでは、カタログを読み取れません。

エクスポート #

エントリーエクスポート
@lingo.dev/react-next/app/servergetLingo()、LingoAppProvider、lingoMetadata(options)、lingoStaticParams(locales)。
@lingo.dev/react-next/app/clientuseLocaleSwitch(locales)とLocaleOption型。
@lingo.dev/react-next/app/proxylingoProxy(locales)。

パッケージのインストール後、コーディングエージェントはlingo agent-guide react-next-appに従って作業できます。next-intlから移行する場合は、lingo agent-guide react-next-migrateに従って進められます。コーディングエージェントでセットアップするを参照してください。