TanStack Startアプリケーションを翻訳する

ロケール接頭辞付きのリクエストを解決し、対応するカタログを読み込んで、正規URLと言語切り替え機能を備えた翻訳済みページを表示します。

読者が/en/aboutや/de/aboutにアクセスしても、/aboutなどのアプリケーションルートは言語に依存しない形に保ちます。@lingo.dev/react-tanstackは、このURLポリシーをリクエストコンテキストとカタログに結び付けます。ルートは引き続き/aboutに一致し、使用するメッセージと生成するURLは、リクエストのロケールによって決まります。

このレシピでは、React 19、TanStack Router 1.170以降、Start 1.168以降を使用する既存のTanStack Startアプリケーションに、英語とドイツ語を追加します。Startは任意のピア依存関係として宣言されていますが、パッケージのルートモジュールはStartのcreateIsomorphicFnをインポートします。Startを使わないRouterアプリケーションでURLを明示的に指定する場合でも、アダプターと併せてStartをインストールしてください。

ロケールポリシーとカタログを定義する#

パッケージをインストールします。

sh
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-tanstack@1.17.1 @lingo.dev/locale-router@0.2.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latest

カタログの読み込みで紹介しているloadMatchedMessages関数を、src/catalog.tsとして追加します。続いてsrc/i18n.tsを作成します。

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";
import type { Catalog } from "@lingo.dev/react-tanstack";
import source from "../locales/en.jsonc?raw";
import { loadMatchedMessages } from "./catalog";

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

const targets = import.meta.glob<string>("../locales/*.jsonc", {
  query: "?raw",
  import: "default",
});

export const catalog: Catalog = async (locale) => {
  const load = targets[`../locales/${locale}.jsonc`];
  if (!load) throw new Error(`Missing catalog for ${locale}`);
  return loadMatchedMessages(source, await load());
};

このViteローダーは元のファイルを検証し、対応する英語ソースから有効なキーを選択します。そのため、コメントを含まない翻訳出力でも、孤立したキーが再び有効になることはありません。ファイルが存在しない場合や形式が不正な場合は、空のマップを黙って返すのではなく、エラーになります。後述の抽出手順で、アプリケーションの起動前にインポート対象のソースを作成します。

ルーターを作成する前にリクエストを解決する#

既存のミドルウェアを残したまま、接頭辞のないパス用のミドルウェアをsrc/start.tsに登録します。

ts
import { createStart } from "@tanstack/react-start";
import { localeMiddleware } from "@lingo.dev/react-tanstack/server";
import { locales } from "./i18n";

export const startInstance = createStart(() => ({
  requestMiddleware: [localeMiddleware(locales)],
}));

src/router.tsxで、解決済みのロケールとメッセージをルーターコンテキストとして使用します。

tsx
import { createRouter } from "@tanstack/react-router";
import { lingoContext, localeRewrite } from "@lingo.dev/react-tanstack";
import { routeTree } from "./routeTree.gen";
import { catalog, locales } from "./i18n";

export async function getRouter() {
  const state = await lingoContext(locales, catalog);
  return createRouter({
    routeTree,
    context: state,
    rewrite: localeRewrite(locales, state.locale),
  });
}

declare module "@tanstack/react-router" {
  interface Register {
    router: Awaited<ReturnType<typeof getRouter>>;
  }
}

アプリケーションのほかのルーター設定はそのまま維持します。lingoContextは認識できるURL接頭辞を使用し、なければ既定のロケールを使用します。サーバーではリクエストURLを、ブラウザではlocation.hrefを読み取ります。省略可能な第3引数URLで、この入力を明示的に指定できます。この関数自体は、Accept-Languageによる言語ネゴシエーションを行いません。対象となる接頭辞なしのパスへのリクエストでは、ミドルウェアがネゴシエーションを行い、302リダイレクトを返します。

localeRewriteは、ルートの照合時に認識済みの接頭辞を取り除き、生成する対象パスにはリクエストのロケールを追加します。ルート定義には接頭辞を付けず、上記のようにAPIやアセットのパスをローカライズの対象から除外してください。

リクエストコンテキストを使ってルートを描画する#

src/routes/__root.tsxで、フレームワークのシェルを維持しながらプロバイダーを組み込みます。

tsx
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from "@tanstack/react-router";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";

type LocaleContext = { locale: "en" | "de"; messages: Messages };

export const Route = createRootRouteWithContext<LocaleContext>()({
  component: Outlet,
  shellComponent: ({ children }) => {
    const { locale, messages } = Route.useRouteContext();
    return (
      <html lang={locale} dir={createLingo(locale).direction}>
        <head>
          <HeadContent />
        </head>
        <body>
          <LingoProvider locale={locale} messages={messages}>
            {children}
          </LingoProvider>
          <Scripts />
        </body>
      </html>
    );
  },
});

これにより、テキスト、書式設定、ドキュメント属性が同じコンテキストに基づいて処理されます。ハイドレーション中もこのコンテキストを維持してください。メッセージをクライアント側の空のマップに置き換えると、描画されるページが変わってしまいます。

翻訳済みページとヘッドメタデータを追加する#

src/routes/about.tsxを作成します。

tsx
import { createFileRoute } from "@tanstack/react-router";
import { useLingo } from "@lingo.dev/react";
import { getLingo, lingoHead } from "@lingo.dev/react-tanstack";
import { locales } from "../i18n";

export const Route = createFileRoute("/about")({
  head: (options) => {
    const l = getLingo(options);
    const localized = lingoHead({
      router: locales,
      locale: options.match.context.locale,
      pathname: options.match.pathname,
      origin: "https://example.com",
    });
    return {
      meta: [{ title: l.text("About us", { context: "About page title" }) }, ...localized.meta],
      links: localized.links,
    };
  },
  component: About,
});

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

例にあるオリジンを、ご自身のサイトの信頼できるオリジンに置き換えてください。head内では、抽出対象の呼び出しより前にconst l = getLingo(options)をバインドします。getLingo(options).text(...)をチェーンする形式は、サポートされている抽出パターンではありません。

ヘッドメタデータ#

lingoHeadは{ meta, links }を返します。これには、各ロケールの正規リンクと代替リンクに加え、x-default、og:url、og:localeが含まれます。クエリやハッシュを含まない、接頭辞なしのパス名を渡してください。ドイツ語の/aboutでは、正規URLはhttps://example.com/de/aboutになります。このポリシーでは、既定の英語の代替URLは/en/aboutになります。

このヘルパーは、ルート以外のパスの末尾からスラッシュを1つ取り除きます。Open Graphのロケールは、de_DEのように言語と地域を最大限に補完した結果から導出されます。省略可能なogLocaleによる上書きで、プラットフォーム固有の表記に対応できます。LingoHeadは戻り値の型であり、NextアダプターのJSXコンポーネントではありません。

カタログを抽出して取得する#

npx lingo extract --src src --source-locale enを実行します。新規設定の場合は、ターゲットをdeにしてlocales/en.jsoncを初期化し、認証を行ってローカライゼーションエンジンをリンクし、最初のターゲットを取得します。

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

既存の設定では、バインディングと詳細設定を維持してください。抽出後、既存のターゲットに対する通常の更新を完了し、取得して内容を確認します。その後、ソースのリビジョンを固定したままdeを追加し、不足分を補完します。この場合は、カタログの読み込みと言語の追加手順に従ってください。locales/en.jsoncと使用する予定のlocales/de.jsoncがそろってから、アプリケーションを起動します。/en/aboutと/de/aboutにアクセスして見出しとタイトルを確認し、それぞれの正規URLと代替URLも確認します。

新しいリクエストで言語を切り替える#

tsx
import { useLocaleSwitch } from "@lingo.dev/react-tanstack";
import { locales } from "./i18n";

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

このコンポーネントをsrcの配下に配置し、ルーティングされたアプリケーション内で描画します。各選択肢には、locale、その言語での自称表記であるlabel、href、currentが含まれます。通常のアンカーリンクは新しいリクエストを送信し、そのロケールのカタログを読み込みます。クライアント側だけで処理するルートリンクでは、前のリクエストのメッセージが残ることがあります。言語切り替え機能はクエリとハッシュを保持し、選択可能な言語からx-defaultを除外します。

組み込みのカタログヘルパーとサーバーヘルパー#

createCatalog(import.meta.glob("../locales/*.jsonc", { query: "?raw" }), { sourceLocale: "en" })は、メタデータをそのまま利用できるファイル向けに、キャッシュ機能付きのCatalogを提供します。各モジュールは、文字列型のdefaultをエクスポートするオブジェクトに解決される必要があります。ファイル内の孤立したキーを除外し、ロケールごとにプロミスを1つキャッシュします。モジュールが存在しない場合や、読み込みエラー、解析エラーが発生した場合は、{}を返します。sourceLocaleが設定されている場合、本番環境ではそのロケールのファイルを読み込まず、ソースをフォールバックとして使用します。値が文字列のフラットな構造かどうかの検証、ルートによる絞り込み、失われたメタデータの復元は行いません。翻訳済みJSONCでこれらが必要な場合は、上記のソース結合ローダーで対応します。

サーバーのエントリーポイントはlocaleMiddlewareとcanonicalSearchをエクスポートします。ミドルウェアは検索パラメーターを保持しますが、TanStackの既定の処理で再シリアル化します。サーバーへのリクエストには、ブラウザのハッシュは含まれません。すでに接頭辞が付いているパス、対象外のパス、または別途正規化の対象となるパスは、next()に進みます。接頭辞と正規化の正確な動作については、locale-routerを参照してください。

Startを使わないTanStack Routerアプリケーションでも、ルートパッケージのStartへの依存関係を維持したまま、lingoContextにURLを渡して独自のリダイレクトを実装できます。このレシピのミドルウェアとリクエストシェルは、Startを対象としています。