プロバイダーとフック

ロケールとカタログを指定し、共通メッセージとページ固有のメッセージを組み合わせ、描画に使う入力を混在させずに言語を切り替えます。

LingoProviderは、コンポーネントのサブツリーで単一のロケールとカタログを利用できるようにします。useLingo()は最も近いプロバイダーを読み取り、その入力に対応するメッセージと書式設定のメソッドを返します。

これらの描画例にはReact 19が必要です。プロバイダーを使う前に、Reactクイックスタートのインストール手順に従ってください。

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

function SaveButton() {
  const l = useLingo();
  return (
    <button type="submit">
      {l.text("Save", { context: "Submit changes to account settings" })}
    </button>
  );
}

export function Settings({ messages }: { messages: Messages }) {
  return (
    <LingoProvider locale="fr" messages={messages}>
      <SaveButton />
    </LingoProvider>
  );
}

Settingsを描画する前に、フランス語のメッセージを読み込んでください。プロバイダーが受け取るMessagesはRecord<string, string>であり、ファイルパスやプロミス、解析済みのJSONCエントリー一覧ではありません。このマップはカタログの読み込みで生成されます。

プロバイダーへの入力 #

プロパティ仕様
localeメッセージ検索の診断、文法、書式設定に使用する必須の文字列。
messagesハッシュをキーとする文字列マップ。省略可能で、既定値は{}。
children必須のReactNodeサブツリー。

カタログが空でも、サブツリーではロケールに応じた書式設定を利用できます。メッセージの呼び出しには、元のテンプレートが使われます。プロバイダー自体は、文書の言語や書字方向を設定しません。

プロバイダー配下のコンポーネントでuseLingoを呼び出してください。プロバイダーの外で呼び出すと例外が発生します。同じコンポーネントからプロバイダーを返しても、そのコンポーネントのフックがプロバイダーの配下に置かれるわけではありません。プロバイダーのラッパーと、フックを読み取るコンポーネントは分けてください。

共通メッセージとページ固有のメッセージを組み合わせる #

入れ子になったプロバイダーのロケール文字列が同じ場合、マップは統合されます。同じキーを持つ親のエントリーは子のエントリーで上書きされ、それ以外の親のエントリーは引き続き利用できます。そのため、ルートでは共通のナビゲーションメッセージを重複して指定せずに、ページ固有のメッセージを追加できます。

tsx
<LingoProvider locale="fr" messages={sharedMessages}>
  <LingoProvider locale="fr" messages={pageMessages}>
    <SettingsPage />
  </LingoProvider>
</LingoProvider>

ここでは、sharedMessagesとpageMessagesは読み込み済みのフランス語のマップです。内側のロケールをesに変更すると、そのプロバイダーは独立します。スペイン語のメッセージが見つからない場合は、フランス語のテキストを流用せず、元のテキストにフォールバックします。比較にはロケール文字列そのものが使われるため、アプリケーション全体でロケールの表記を統一してください。

ロケールとカタログを同時に切り替える #

描画に使う入力は、{ locale: "fr", messages: frenchMessages }のようなペアで保持します。次のマップを読み込んでから、1回の状態更新でペアを置き換えてください。ロケールだけを変更すると、フランス語のテキストが表示されたまま、数値の書式だけがスペイン語になることがあります。

次のカタログを読み込んでいる間は、アプリケーションの操作設計に応じて、直前のペアによる表示を維持するか、読み込み中の状態を表示してください。ルーティングを使うアプリケーションでは、対応するNext PagesまたはTanStackの実装例を参照してください。それぞれの切り替え処理で、新しい入力の読み込み方法が異なります。

フックを使わずにLingoオブジェクトを作成する #

Reactコンポーネントの外で関数が文字列を必要とする場合は、createLingo(locale: string, messages?: Messages): Lingoを使います。

ts
import { createLingo } from "@lingo.dev/react";

const l = createLingo("en-US");
const title = l.text("Account settings", { context: "Settings page title" });
const percentage = l.percent(0.125, { maximumFractionDigits: 1 });

この呼び出しはAccount settingsを返し、このロケールに合わせて比率を12.5%の形式に整えます。翻訳リクエストは送信せず、プロバイダーの変更も購読しません。ロケールやメッセージが変わったら、新しいオブジェクトを作成してください。

createLingoとuseLingoは、どちらもlocale、direction、script、regionを公開します。文書の属性を適用するにはロケールのメタデータを使い、ハイドレーション時にも同じ入力を維持してください。