ロケールと書字方向

ランタイムのロケールメタデータを使って、文書やローカライズされたサブツリーに言語と書字方向を設定します。

翻訳されたテキストと文書の書字方向は、互いに一致している必要があります。アラビア語のカタログを渡すとメッセージは切り替わりますが、ブラウザが意図した書字方向でページをレイアウトするには、dir="rtl"も必要です。プロバイダーと文書属性の両方に、解決済みのロケールを使ってください。

言語と書字方向を同時に設定する #

フレームワークの文書コンポーネントまたはシェルコンポーネントで、そのリクエスト用に選択されたロケールから属性を求めます。

tsx
import type { ReactNode } from "react";
import { createLingo, LingoProvider, type Messages } from "@lingo.dev/react";

export function LocalizedDocument({ locale, messages, children }: {
  locale: string;
  messages: Messages;
  children: ReactNode;
}) {
  const l = createLingo(locale);
  return (
    <html lang={l.locale} dir={l.direction}>
      <body>
        <LingoProvider locale={locale} messages={messages}>
          {children}
        </LingoProvider>
      </body>
    </html>
  );
}

このパターンを組み込む際も、フレームワークに必要なヘッド、スクリプト、ハイドレーションの各コンポーネントは残してください。別の言語のページ内にあるローカライズされたサブツリーでは、そのサブツリーのuseLingo()の結果を使い、サブツリーを囲む要素にlangとdirを設定します。セクションに属性を設定しても、文書全体の言語設定は置き換わりません。

可能な限り、最初に出力するHTMLに属性を適用してください。ハイドレーション後に書字方向を更新するだけでは、ページが最初に誤ったレイアウトで表示されることがあります。

メタデータを正確に読み取る #

メンバー意味
locale: string入力されたロケールの値。変更されません。
direction: "ltr" | "rtl"利用可能な場合はネイティブのIntl.Locale.textInfoが示す書字方向。それ以外の場合は、ランタイムが言語に基づいて決定するフォールバック値。
script: string | undefinedIntl.Localeでロケールを最大化して得られる、推定の用字系。
region: string | undefined同じ最大化処理で得られる、推定の地域。

たとえば、createLingo("en")からLatnとUSを推定できます。これはロケールのサブタグを推定して補完するもので、閲覧者の所在地や請求先の国を特定するものではありません。アプリケーションでこうした情報が必要な場合は、実際のアカウント情報や位置情報を使ってください。

Intl.Localeが利用できない場合やタグが無効な場合、用字系と地域が未定義になることがあり、書字方向にはフォールバック用の言語リストが使われます。また、ほかのネイティブフォーマッターでは、無効なタグが拒否されることもあります。描画前に、アプリケーションが対応するロケールの一覧に照らして、使用するロケールを解決してください。

レイアウトを書字方向に合わせる #

書字方向に合わせて余白を調整するには、margin-inline-startやpadding-inline-endなどのCSS論理プロパティを使ってください。アイコンは個別に確認しましょう。ナビゲーションの矢印は反転が必要な場合がありますが、実物を描いた画像では不要な場合があります。ロケールメタデータが書字方向を示し、それを画面にどう反映するかはコンポーネントの設計で決まります。

プロバイダーは言語のネゴシエーションもメッセージの取得も行いません。ロケールルーターがURLと優先設定に関するポリシーを提供します。Next Pagesラッパーは書字方向を同期しますが、文書のlangの設定はアプリケーションに委ねます。TanStackシェルはリクエストのコンテキストに基づいて両方を設定します。

言語を切り替えた後は、文書属性と読み込まれたカタログを併せて確認してください。サーバーレンダリングでは、同じロケール、メッセージ、書式設定用の入力値をハイドレーションにも渡す必要がある理由を説明しています。