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を通じてロケールを読み取ります。まず、パッケージをインストールします。
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)。
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を作成します。
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キーがある場合は削除してください。アプリルーターはこのキーを読み取りません。
// 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が提供します。どちらも、ロケールを受け渡す必要はありません。
// 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]セグメントが見つからず、エラーがスローされます。
メタデータを追加する #
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()、パスを指定するフォームアクションにも同じことが当てはまります。
"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などのドットで始まるフォルダーはスキップされます。新しく設定する場合は、次を実行します。
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 --waitinitは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/server | getLingo()、LingoAppProvider、lingoMetadata(options)、lingoStaticParams(locales)。 |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales)とLocaleOption型。 |
@lingo.dev/react-next/app/proxy | lingoProxy(locales)。 |
パッケージのインストール後、コーディングエージェントはlingo agent-guide react-next-appに従って作業できます。next-intlから移行する場合は、lingo agent-guide react-next-migrateに従って進められます。コーディングエージェントでセットアップするを参照してください。