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

ページの翻訳済みメッセージを読み込んでページ用ラッパー経由で表示し、ロケールの切り替えと代替リンクを追加します。

Next.jsのページルーターでは、リクエストに対応するロケールがルートですでに解決されています。@lingo.dev/react-nextはそのロケールに基づいてReactのメッセージを提供し、ページデータと翻訳テキストをまとめて扱います。この手順では、紹介ページを英語とフランス語で表示し、翻訳済みのJSONCからメタデータが失われた場合でも、ルートの選択を維持します。

React 19を使用する既存のページルーターのアプリケーションを用意してください。このパッケージは、ピア依存関係としてNext.js 13以降とReact 18または19を宣言していますが、現在の実行時プロバイダーはReact 19のコンテキスト省略記法を使用しています。エクスポートは/pages、/pages/client、/pages/serverです。ルートエクスポートやアプリルーター用のエントリーポイントはありません。

ロケールとアプリのラッパーを設定する #

sh
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latest

既存のnext.config.mjsに、ほかの設定を維持したまま国際化設定を追加します。

js
export default {
  i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};

pages/_app.tsxでアプリケーションをラップします。

tsx
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";

function App({ Component, pageProps }: AppProps) {
  const { locale, defaultLocale } = useRouter();
  useEffect(() => {
    document.documentElement.lang = locale ?? defaultLocale ?? "en";
  }, [locale, defaultLocale]);
  return <Component {...pageProps} />;
}

export default withLingoApp(App);

ラッパーはpageProps.__lingoMessagesを読み取り、Next.jsで現在有効なロケールを解決して、LingoProviderを提供します。URLの扱いはNext.js自体の国際化設定で決まります。既定の英語のパスには、通常プレフィックスが付きません。

ページを作成してメッセージを読み込む #

まず、カタログの読み込みで紹介しているloadMatchedMessages関数をlib/catalog.tsとして追加します。この関数は、値が文字列のJSONCを検証し、翻訳先の値を現在有効な翻訳元のキーに結合します。

次に、pages/about.tsxを作成します。

tsx
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";

export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
  const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
  if (!["en", "fr"].includes(locale)) return { notFound: true };
  const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
  const target =
    locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
  const messages = loadMatchedMessages(source, target, (entry) => {
    const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
    return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
  });
  return { props: { __lingoMessages: messages } };
};

export default function About() {
  const l = useLingo();
  return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}

この判定関数は、ページ自体のエントリーと共有コンポーネントのメッセージを残します。翻訳元のメタデータからは、拡張子と旧形式の行番号サフィックスを取り除きます。ページがsrc/pages/about.tsxにある場合は、インポートパスとルートの比較条件の両方を、それに合わせて更新してください。

カスタムローダーは、必須ファイルが見つからない場合や形式が不正な場合に、意図的に失敗する設計です。これにより、ビルド時に想定していたフランス語のカタログが、気づかないうちに英語のフォールバックに置き換わるのを防ぎます。翻訳先の個々のキーが欠けている場合は、そのまま欠落として扱われ、通常の実行時フォールバックが使われます。

抽出・翻訳して両方のルートを開く #

プロジェクトのルートでnpx lingo extract --src pages --source-locale enを実行します。Lingo.devのプロジェクト設定を新しく作成する場合は、次を実行します。

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

設定済みのプロジェクトでは、既存の紐付けとその他のファイルオプションを維持してください。抽出後、既存の翻訳先ロケールに対する通常の更新を完了し、取得して内容を確認します。その後、翻訳元のリビジョンを変更せずにfrを追加し、不足分を補完します。設定手順はカタログの読み込みで、必要な作業順序は言語を追加するで説明しています。共有コンポーネントがpagesの外にある場合は、すべてのメッセージ呼び出しを含むディレクトリから抽出するか、共通のsrcツリー配下にまとめて--src srcを使用してください。

locales/fr.jsoncを取得したら、通常のNext.jsの開発用コマンドまたはビルドコマンドを実行します。/aboutと/fr/aboutを開いてください。前者は英語の翻訳元を使い、後者は同じ見出しキーのフランス語訳を使います。実際に表示されるフランス語のテキストと、意図的に欠落させたエントリーで翻訳元へのフォールバックが行われることを確認してください。

組み込み機能で静的プロパティを読み込む #

各ロケールファイルに正しい@srcと@orphanのメタデータが保持されていれば、サーバーヘルパーで上記のカスタムgetStaticPropsを置き換えられます。

ts
import { withLingoProps } from "@lingo.dev/react-next/pages/server";

export const getStaticProps = withLingoProps({ route: "pages/about" });

withLingoProps({ route, handler? })は、作業ディレクトリを基準とする固定のlocales/<locale>.jsoncパスから読み込みます。対応する翻訳元がなくなったエントリーや、ほかのページのエントリーを除外し、ページ以外のソースと@srcのないエントリーは共有として扱います。一般的なJSONCの翻訳では@orphanのマークは保持されますが、@srcのコメントは削除されます。その出力には、上記の翻訳元キーで結合する手順を使用してください。このヘルパーはメタデータを復元しません。

ファイルが見つからない場合は{}が返され、開発時には警告が表示されます。既存のファイルが不正な場合は、例外が発生することがあります。任意の非同期ハンドラーを指定すると、プロパティを追加したり、リダイレクトや未検出の結果を返したりできます。成功時の結果にはrevalidateなどのフィールドが保持され、__lingoMessagesが追加されます。公開されている型は、静的プロパティのコンテキストと結果を使用します。任意のサーバー側リクエストハンドラーも同じ仕様に従うとは限りません。また、CLIでカタログパスを上書きしても、このローダーの固定の読み込み先ディレクトリは変わりません。

動的ルートの静的パスを展開する #

動的ルートでは、サーバーヘルパーが各パラメーターエントリーを、Next.jsに設定された各ロケールに展開します。

ts
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";

export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
  fallback: "blocking",
});

既定のフォールバックは"blocking"です。falseとtrueにも対応しています。この展開ではスラッグは翻訳されず、すべてのカタログにそのルートのメッセージが含まれていることも保証されません。

言語を切り替えて代替リンクを追加する #

アプリのラッパー配下に、言語の切り替えコントロールを表示します。

tsx
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";

export function Languages() {
  const switchLocale = useLocaleSwitch();
  return (
    <nav aria-label="Language">
      <LingoHead baseUrl="https://example.com" />
      <button onClick={() => switchLocale("en")}>English</button>
      <button onClick={() => switchLocale("fr")}>Français</button>
    </nav>
  );
}

例のオリジンを、サイトの本番環境の絶対オリジンに置き換えてください。LingoHeadは、設定済みのロケールとx-defaultに対応する代替リンクを出力し、既定のロケールのプレフィックスは省略します。正規URLやオープングラフのメタデータは出力しません。生成されたURLが、ルートとクエリの扱いに合っているか確認してください。

切り替え時のコールバックは、NEXT_LOCALEを有効期間1年、パス/、SameSite=Laxで書き込んだ後、現在のasPathを使ってNext.jsのルーターで移動します。上記のように、設定済みのロケールを渡してください。任意の入力が対応ロケールの一覧に含まれるかどうかは検証されません。

ドキュメントの初期属性を設定する #

既存のドキュメントのカスタマイズを維持したまま、pages/_document.tsxで初期属性を設定します。

tsx
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";

export default class LocalizedDocument extends Document {
  render() {
    const locale = this.props.__NEXT_DATA__.locale ?? "en";
    return (
      <Html lang={locale} dir={createLingo(locale).direction}>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

withLingoAppはロケールの変更後に書字方向を設定し、初期表示用に右から左への書字方向を設定するインラインスクリプトを出力しますが、langは設定しません。上記の_appのエフェクトは、画面遷移時にlangを更新します。カスタムドキュメントは、両方の初期属性を設定します。厳格なコンテンツセキュリティポリシーでは、ラッパーのインラインスクリプトがブロックされる場合がありますが、ラッパーにはノンスを指定するオプションがありません。カスタムドキュメントなら、そのスクリプトに依存せずに初期の書字方向を設定できます。画面遷移時のアプリケーションのスクリプトポリシーも確認してください。

最後に、同じカタログと明示的に指定した時刻を使ってハイドレーションを確認します。言語を切り替えたときに、メッセージとドキュメント属性が同時に変わることを確認してください。