React のメッセージ
原文とコンテキストをコンポーネント内にまとめ、値や文法、React 要素を反映しながら翻訳済みカタログをレンダリングします。
コンポーネントのメッセージは、そのメッセージが説明する操作と同じ場所に置きましょう。フォームの「保存」は変更を送信する操作ですが、記事の「保存」はブックマークを作成する操作です。原文とその意味を一緒に管理すれば、翻訳者はこの違いを把握でき、開発者も別のファイルでキーを調べずにコンポーネントを理解できます。
@lingo.dev/react では、メッセージを明示的に呼び出します。
import { useLingo } from "@lingo.dev/react";
export function SaveButton() {
const l = useLingo();
return <button type="submit">{l.text("Save", { context: "Submit changes to account settings" })}</button>;
}原文とコンテキストによって、カタログ内のメッセージが識別されます。カタログは、キーと翻訳済み文字列を対応付けたものです。プロバイダーは、そのカタログと使用中のロケールを提供します。コンポーネントは翻訳済みテキストを受け取り、該当する項目がない場合や空の場合は、代わりに原文を受け取ります。
コンポーネントから別の言語へ #
まずは、ローカルで翻訳をレンダリングしてみましょう。小さなカタログを使えば、アカウントやネットワークリクエストなしで、メッセージを検索する仕組みを確認できます。
アプリケーションのワークフローでは、lingo extract が認識できる呼び出しを原文の JSONC カタログに集め、TypeScript の型宣言を生成します。CLI はそのファイルを翻訳用に送信し、翻訳先のファイルを取得します。ローダーはそのファイルを、プロバイダーで使う文字列マップに変換します。カタログの抽出と読み込みでは、この一連の流れに加え、翻訳済みの JSONC からメタデータのコメントが失われた場合に、使用中のメッセージを保持する方法も説明します。
レンダリングはローカルで行われます。ランタイムはローカライゼーションエンジンに接続せず、API キーも保持しません。サーバー側の翻訳は API 連携で行い、生成されたカタログは、通常のビルド処理やリクエスト時の読み込み処理を通じてアプリケーションに配信してください。
読み手に必要なメッセージを書く #
個別に翻訳した断片をつなぎ合わせるのではなく、プレースホルダーを含む一つの文を使いましょう。言語が変わると、名前や件数、リンクを置く位置も変わることがあります。
| メッセージに必要なもの | 使用するもの |
|---|---|
| 値を含むプレーンテキスト | l.text。 |
| リンク、強調、その他の React 要素 | l.rich と、名前付きのレンダリング用コールバック。 |
| 数量に応じた文法やカテゴリによる選択 | l.plural と l.select。 |
| 数値、日付、リスト、ロケールに応じたテキスト操作 | ネイティブの Intl を使用する書式設定メソッド。 |
プロバイダーとフックのリファレンスでは、入れ子になったカタログと、コンポーネント外のコードで使う createLingo について説明します。ロケールのメタデータは、文書やレイアウトを適切に設計できるよう、文字の方向、文字体系、地域の情報を提供します。
メッセージを軸にアプリケーションをつなぐ #
Next.js Pages と TanStack Start のアダプターは、カタログをそれぞれのルーティングシステムに接続します。それ以外の構成では、レンダリング前にロケールとメッセージを読み込み、サーバーレンダリングとハイドレーションの間もその組み合わせを維持してください。
生成された型を使えば、編集中に原文、コンテキスト、値の誤りを検出できます。レンダリングテストでは、実際に読み込まれたテンプレートを確認しましょう。翻訳が表示されない場合は、トラブルシューティングに沿って、コンポーネントからカタログまでの検索処理をたどってください。
エクスポート #
ルートからは LingoProvider、useLingo、createLingo、computeKey に加え、型 LingoProviderProps、Lingo、Messages、LingoMessages、MessageKey、TextOptions、RichOptions、PluralForms、SelectForms、FormatMethods がエクスポートされます。別の @lingo.dev/react/testing エントリーからは、withLingo と renderStatic がエクスポートされます。