useLingo

useLingo() は、コンポーネントからランタイムを利用するための入口です。最も近い <LingoProvider> を参照し、現在アクティブな Lingo オブジェクトを返します。各コンポーネントで 1 回だけ呼び出し、参照を保持したうえで必要なメソッドを使ってください。

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}

プロバイダーの外で呼び出すと例外が発生するため、テストでは render をラップする必要があります。テスト内で翻訳自体を気にしない場合でも、messages: {} でラップしてください。

`l.text(source, options)` — 通常の文字列#

もっとも基本的な呼び出しです。翻訳済みの文字列を返し、現在のロケールに翻訳が存在しない場合はソース文字列をそのまま返します。

tsx

l.text("Save", { context: "Form button" });
// → "Speichern" (de) / "Save" (en, fallback)

補間#

{placeholder} のセグメントは options.values の値で置き換えられます。

tsx

l.text("Welcome back, {name}!", {
  values: { name: user.firstName },
  context: "Dashboard greeting",
});

値が不足している場合は、{name} がそのまま表示されます。開発中にバグを見つけやすくなりますが、空の値が見逃されないよう、テストではレンダリング結果を必ず検証してください。

ソースに ICU 構文が含まれている場合#

ソース文字列に plural / select / number / date マーカーが含まれている場合、ランタイムが自動的に対応します。追加の API は不要です。使いやすいラッパーについては、複数形と select を参照してください。

`l.rich(source, options)` — React サブツリー#

翻訳済みテキストに React コンポーネント（リンク、太字、<Icon/> など）が含まれる場合は、l.rich を使います。翻訳文字列には <link>...</link> のようなプレースホルダータグが入り、各タグをレンダラーに対応付けます。

tsx

l.rich("Click <link>here</link> for {topic}", {
  tags: {
    link: (children) => <a href="/help">{children}</a>,
  },
  values: { topic: "details" },
  context: "Footer help link",
});
// → <>Click <a href="/help">here</a> for details</>

自己終了タグも使えます。

tsx

l.rich("Loading <spinner/>...", {
  tags: { spinner: () => <Spinner /> },
  context: "Inline loading state",
});

レンダラーなしのタグは生のテキストにフォールバックします。つまり、タグ不足は開発中に目に見える形で現れ、黙って無視されることはありません。

翻訳文字列の中にマークアップを直接書かないでください。l.rich があるのは、翻訳者に <a href="..."> ではなく中立的なプレースホルダー（<link>）を見せるためです。<a href="..."> はそのまま維持する必要があり、壊れやすいためです。レンダラーはロケールファイルではなく、コード内で定義してください。

`l` のロケールメタデータ#

翻訳機能に加えて、このオブジェクトでは次の情報も参照できます。

プロパティ	型	備考
`l.locale`	`string`	`LingoProvider` に渡した値です。BCP-47。
`l.direction`	`"ltr"` \| `"rtl"`	`Intl.Locale.textInfo` とフォールバック用の RTL 言語リストをもとに算出されます。
`l.script`	`string` \| `undefined`	可能な場合は自動推定されます（`"Latn"`、`"Cyrl"`、`"Arab"`、…）。
`l.region`	`string` \| `undefined`	BCP-47 から推定されます（`"US"`、`"DE"`、`"SA"`、…）。

レイアウトの判断にも役立ちます。

tsx

const l = useLingo();
return <div dir={l.direction}>...</div>;

l には num、currency、percent、date、time、datetime、relative、list、displayName、sort、segment、fileSize、compact、unit も用意されています。全体の詳細は Formatting を参照してください。これらは l.locale に合わせて動作するネイティブ Intl.* フォーマッターの薄いラッパーです。

React の外で使う場合#

useLingo が使えるのはコンポーネント内だけです。ユーティリティ、ルートローダー、サーバーコードでは、同じオブジェクトを直接構築してください。

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

const l = createLingo("es", messages);
l.text("Hello", { context: "Email subject" });

返されるのは同じ Lingo 形式のオブジェクトで、プロバイダーは不要です。LingoProvider 自体も内部では createLingo を使っています。

tsx

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

function Greeting() {
  const l = useLingo();
  return <p>{l.text("Hello", { context: "Hero heading" })}</p>;
}