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をインストールしてください。
ロケールポリシーとカタログを定義する#
パッケージをインストールします。
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を作成します。
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に登録します。
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で、解決済みのロケールとメッセージをルーターコンテキストとして使用します。
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で、フレームワークのシェルを維持しながらプロバイダーを組み込みます。
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を作成します。
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を初期化し、認証を行ってローカライゼーションエンジンをリンクし、最初のターゲットを取得します。
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も確認します。
新しいリクエストで言語を切り替える#
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を対象としています。