操作できるリッチなメッセージをローカライズする

リンク、コンポーネント、値は React コードで制御したまま、文全体を翻訳します。

「続行する前にポリシーをお読みください」は、「ポリシー」がリンクでも一つの文です。文全体を一つの翻訳として扱えば、リンク先の制御はアプリケーションコードに残したまま、翻訳先の言語に合わせてリンクを適切な位置に移せます。

React パッケージの rich メソッドは、このリンクを名前付きスロットとして表現します。カタログが文を提供し、React レンダラーがそのスロットに対応するコンポーネントを提供します。

リンクを含む文を丸ごと描画する #

既存の React 19 アプリケーションに @lingo.dev/react をインストールします。このローカルで動かす例では、説明用のスペイン語カタログを使うため、翻訳リクエストは不要です。

sh
npm install @lingo.dev/react
tsx
import { computeKey, LingoProvider, useLingo } from "@lingo.dev/react";

const messages = {
  [computeKey(
    "Read the <policy>policy</policy> before continuing.",
    "Notice before account creation",
  )]: "Antes de continuar, lee la <policy>política</policy>.",
};

function ConsentNotice() {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <policy>policy</policy> before continuing.", {
        context: "Notice before account creation",
        tags: {
          policy: (children) => <a href="/policy">{children}</a>,
        },
      })}
    </p>
  );
}

export function App() {
  return (
    <LingoProvider locale="es" messages={messages}>
      <ConsentNotice />
    </LingoProvider>
  );
}

段落には、「続行する前に、ポリシーをお読みください。」という意味のスペイン語の文が表示されます。翻訳によってポリシーに言及する位置は変わりますが、リンク先は引き続き /policy です。また、呼び出し内にソース文とコンテキストをリテラルで記述することで、抽出時にメッセージを認識できるようになります。computeKey は、仮のハッシュに頼らず、テストデータの実際の識別情報を生成します。

パッケージはピア依存関係として React 18 と 19 を宣言していますが、現在のプロバイダーは React 19 のコンテキスト構文を使っています。React 18 での動作は別途確認してください。プロバイダーの設定と最初のカタログについては、React クイックスタートで説明しています。

値と動作はコードで管理する #

policy という名前が示すのはスロットであり、翻訳者が指定する HTML 要素ではありません。リンク先と動作は、そのレンダラーが管理します。ロケールごとのリンク先は、コード内の既知のルート対応表から決定してください。イベントハンドラーや任意の HTML 属性は、カタログに含めないでください。

変化する値には、名前付きプレースホルダーを使います。

tsx
const greeting = l.text("Welcome, {name}", {
  context: "Greeting on the signed-in account page",
  values: { name },
});

const countLabel = l.plural(
  count,
  { one: "# item", other: "# items" },
  { context: "Number of items in the cart" },
);

const roleLabel = l.select(
  role,
  { admin: "Administrator", other: "Member" },
  { context: "Account role label" },
);

これらの呼び出しは、const l = useLingo() と、name、count、role に対応するアプリケーションの値を持つコンポーネント内に記述します。text はプレーンテキストを返し、plural は個数に応じた文法形式を決定します。select はセレクターの完全一致で分岐し、一致しない場合は other にフォールバックします。リッチテキストの処理は名前付きタグと単純な値の補間に対応していますが、プレーンテキストの処理で使う複雑な ICU フォーマッターは実行しません。こうした実行時の判断には、複数形、日付、数値の機能を使ってください。

ソースは静的な文字列にしてください。ソース文字列に人名を埋め込むと、人ごとに異なるソース文が作られ、確実に抽出できなくなります。識別情報はソースとコンテキストの組み合わせで決まるため、コンテキストには「アカウントのロールラベル」のように用途を記述してください。翻訳の作成後にコンテキストを変更する場合は、慎重に行ってください。

ローカルのテストデータを抽出したカタログに置き換える #

現行版の CLI をインストールした状態で、次を実行します。

sh
lingo extract --src src --source-locale en

パスを上書きしない場合は、locales/en.jsonc と lingo.d.ts が書き出されます。抽出されたソース、コンテキスト、キーを確認してください。宣言はアプリケーションの TypeScript 設定に含めます。抽出は認識可能なメッセージ呼び出しに対応していますが、動的に生成された任意のソース文字列は検出しません。

CLI クイックスタートに従って認証とローカライゼーションエンジンの関連付けを行い、.lingo/config.json で、この実際の locales/en.jsonc ソースと必要な翻訳先ロケールを選択します。このファイルベースのワークフローで、カタログを翻訳して取得します。カタログの読み込み手順に従って JSONC を解析し、対応するソースリビジョンから有効なキーを選び、翻訳先の文字列をプロバイダーに渡してください。汎用のファイル翻訳機能では、ソースカタログのコメントは翻訳先の出力に保持されません。

取得したスペイン語カタログを使って、同じ通知を読み込みます。項目が欠落している場合や空の場合はソース文にフォールバックするため、表示結果だけでなく、必要な翻訳先キーも照合してください。

操作と形式不正のケースをテストする #

キーボードでポリシーのリンクを開き、アクセシブルな名前を確認してください。リンクの位置が変わった後は、前後の句読点も確認します。翻訳を完成させるには、文の意味だけでなく、読者が実行できる操作も保持する必要があります。

ローカルのカタログ用テストデータで、タグハンドラーを削除する、未知のタグを追加する、タグを閉じずに残す、といったケースを試してください。現在のレンダラーは、未知のマークアップや対応するタグがないマークアップをテキストとして残します。同名タグを入れ子にした場合の対応付けには制限があります。任意の HTML を描画するレンダラーでも、形式が不正なメッセージをすべて拒否するバリデーターでもありません。

プレーンテキストでは、値が欠けている場合と、複雑な ICU メッセージの形式が不正な場合を確認してください。未解決のプレースホルダーや未整形のテンプレートがそのまま表示され、開発時の診断情報が出力されることがあります。個数とロールのメッセージでは、翻訳先言語の複数形カテゴリと未知のロールをテストします。これらの確認で対象となる正確な動作については、リッチテキストのリファレンスとReact のテストガイドを参照してください。