プロバイダーとフック
ロケールとカタログを指定し、共通メッセージとページ固有のメッセージを組み合わせ、描画に使う入力を混在させずに言語を切り替えます。
LingoProviderは、コンポーネントのサブツリーで単一のロケールとカタログを利用できるようにします。useLingo()は最も近いプロバイダーを読み取り、その入力に対応するメッセージと書式設定のメソッドを返します。
これらの描画例にはReact 19が必要です。プロバイダーを使う前に、Reactクイックスタートのインストール手順に従ってください。
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を呼び出してください。プロバイダーの外で呼び出すと例外が発生します。同じコンポーネントからプロバイダーを返しても、そのコンポーネントのフックがプロバイダーの配下に置かれるわけではありません。プロバイダーのラッパーと、フックを読み取るコンポーネントは分けてください。
共通メッセージとページ固有のメッセージを組み合わせる #
入れ子になったプロバイダーのロケール文字列が同じ場合、マップは統合されます。同じキーを持つ親のエントリーは子のエントリーで上書きされ、それ以外の親のエントリーは引き続き利用できます。そのため、ルートでは共通のナビゲーションメッセージを重複して指定せずに、ページ固有のメッセージを追加できます。
<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を使います。
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を公開します。文書の属性を適用するにはロケールのメタデータを使い、ハイドレーション時にも同じ入力を維持してください。