ロケールのURLポリシー

フレームワークに依存せず、ロケールのプレフィックスを定義し、優先設定に基づく言語の選択や、リダイレクト先と代替パスの決定を行います。

ローカライズされたURLには、一貫したポリシーが必要です。対応する言語、パス内での言語の表し方、プレフィックスのないパスからの誘導先を決めます。@lingo.dev/locale-routerは、ネイティブのIntlを使ってこれらを判断します。サーバーがリダイレクトを送信し、アプリケーションが選択されたカタログを読み込みます。

対応ロケールとスラッグを定義する #

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

const locales = createLocaleRouter(["en", "de", "pt-BR"] as const, {
  defaultLocale: "en",
  exclude: ["api", "assets"],
  slugs: { "pt-BR": "br" },
});

ロケールpt-BRはブラジルポルトガル語を表し、brはURLで使うスラッグにすぎません。上書きしない場合、スラッグには小文字のロケールタグが使われます。有効なタグ、対応ロケールの中から選んだ既定値、重複のない小文字のスラッグを使用してください。コンストラクターは、設定の競合をすべて検証するわけではありません。

createLocaleRouter<L extends string>(locales, options)は読み取り専用のロケール配列を受け取り、LocaleRouter<L>を返します。defaultLocaleは必須で、excludeとslugsは省略可能です。除外条件は、パス名の最初のセグメントと照合されます。最初のセグメントが_で始まる場合や、.を含む場合も除外されるため、内部パスやファイルパスはローカライズの対象になりません。

プレフィックスのないURLからリダイレクト先を決定する #

ts
const target = locales.redirect(
  new URL("https://example.com/account?tab=billing#details"),
  "de-CH,de;q=0.8,en;q=0.5",
);

if (target) {
  console.log(target.href);
}

これによりhttps://example.com/de/account?tab=billing#detailsが生成されます。スイスドイツ語の優先設定は、対応言語のドイツ語に一致します。このヘルパーは新しいURLを返すだけで、HTTPレスポンスの送信やクッキーの設定は行いません。サーバーがステータスを選び、リダイレクト先を送信します。URLヘルパーは渡されたフラグメントを保持しますが、実際のHTTPリクエストにはブラウザのフラグメントは含まれません。

保存済みの優先設定を優先させる場合は、toLocaleでそのロケールタグを検証し、結果をredirectの省略可能な第3引数として渡してください。任意の文字列を対応ロケールとして渡さないでください。

パスを調べて組み立てる #

上記のポリシーでの呼び出し結果
locales.toLocale("pt_BR")"pt-BR"。ロケールの完全一致を確認する前に、アンダースコアが正規化されます。
locales.toLocale("br")undefined。URLスラッグとロケールタグは別のものです。
locales.split("/br/account"){ locale: "pt-BR", rest: "/account" }。
locales.isLocalized("/account")true。ローカライズの対象になることを示しており、すでにプレフィックスが付いているという意味ではありません。
locales.prefix("/account", "de")"/de/account"。
locales.prefix("/", "de")"/de"。
locales.prefix("/api/status", "de")"/api/status"。変更はありません。
locales.canonical("/DE/account")"/de/account"。

splitは、最初のセグメントのスラッグを認識できない場合、未定義値を返します。パスを扱うメソッドには、クエリパラメーターやハッシュを含む文字列ではなく、パス名を渡してください。

prefixとalternatesには、プレフィックスのないパスを渡す必要があります。/br/accountをドイツ語に変更するには、パスを分割してrestを渡してください。

ts
const current = locales.split("/br/account");
const germanPath = current ? locales.prefix(current.rest, "de") : undefined;

結果は/de/accountになります。元のパスに直接プレフィックスを付けると、ロケールのセグメントが二重に追加されることがあります。

優先設定に基づいて言語を選ぶ #

negotiate(acceptLanguage: string | null): Lは、品質値が正の優先設定を品質値順に並べ、順番に試します。各優先設定について、まずロケールの完全一致を確認し、次に対応言語との一致を確認します。同じ言語の地域別ロケールが複数サポートされている場合、設定された順序によって言語のフォールバック先が決まることがあります。

無効な品質値と、品質値がゼロの優先設定は破棄されます。無効なタグは一致せず、ワイルドカードが既定のポリシーを置き換えることもありません。どの優先設定にも一致しない場合、このメソッドはdefaultLocaleを返します。言語の選択は、位置情報ではなく、指定された優先設定に基づきます。

正規化とプレフィックスのないパスのリダイレクトを分けて扱う #

canonical(pathname): string | undefinedは、最初のセグメントをロケールらしい形式として認識すると、正規化したスラッグを提案します。汎用的な正規URL生成機能ではありません。redirectは、すでにプレフィックスが付いているパス、除外対象のパス、canonicalが修正を提案できるパスに対して、未定義値を返します。

アプリケーションで/DE/accountの正規化が必要な場合は、別途処理してください。サーバーでは、リクエストURLのコピーでクエリ文字列を保持したままパス名を置き換えてから、選択したリダイレクトを送信できます。TanStackのミドルウェアは、プレフィックスのないパスで優先設定に基づく言語の選択を処理しますが、この正規化処理は別途行う必要があります。

別言語のURLを生成する #

ts
const links = locales.alternates("/account").map(({ locale, pathname }) => ({
  hrefLang: locale,
  href: new URL(pathname, "https://example.com").href,
}));

例にあるオリジンではなく、サイトの信頼できるオリジンを使用してください。alternatesは、対応する各ロケールにつき1つの{ locale, pathname }と、既定のロケールのパスを指すx-defaultを返します。pt-BRの言語エントリには/br/accountを使用します。このポリシーでは、既定の英語エントリには/en/accountを使用します。

呼び出し側がこれらをメタデータとして出力します。TanStackのヘッドメタデータは、このポリシーに加えて正規URLとOpen Graphのフィールドを追加します。Next Pagesアダプターは、既定のロケールのURLについてNext独自の異なるポリシーに従うため、両者の出力を相互に置き換えて使わないでください。