リッチテキストメッセージ

リンク先やReactの動作はアプリケーションコードで管理したまま、文全体を翻訳します。

リンクは文の一部として使われることがよくあります。リンクの前後とリンク内のテキストを別々に翻訳すると、原文の語順に縛られてしまいます。l.richを使えば、文全体をまとめて翻訳でき、翻訳後のテンプレートで名前付きのReact要素を適切な位置に配置できます。

文をひとまとまりに保つ #

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

export function PurchaseNotice({ product }: { product: string }) {
  const l = useLingo();
  return (
    <p>
      {l.rich("Read the <link>refund policy</link> before buying {product}.", {
        context: "Purchase notice linking to the refund policy",
        values: { product },
        tags: {
          link: (children) => <a href="/refund-policy">{children}</a>,
        },
      })}
    </p>
  );
}

このコンポーネントはプロバイダーの配下で描画してください。l.textと同じように、原文とコンテキストに基づいてカタログのエントリが選択されます。翻訳後のテンプレートが文言とタグの配置を決め、コールバックがリンク先、属性、スタイル、動作を指定します。

l.richはReactNodeを返します。そのRichOptionsではcontextが必須で、文字列または数値を値とするvaluesのマップと、tags: Record<string, (children: ReactNode) => ReactNode>を指定できます。タグ名は完全に一致する必要があるため、<link>にはlinkコールバックが必要です。

子要素のない要素を挿入する #

自己終了タグは、子要素としてnullを渡してレンダラーを呼び出します。たとえば、次の確認メッセージでは、メッセージの後ろに装飾用のアイコンを配置しています。

tsx
const confirmation = l.rich("Saved <icon/>", {
  context: "Confirmation that account settings were saved",
  tags: {
    icon: () => <span aria-hidden="true">✓</span>,
  },
});

ここで、lはコンポーネントのuseLingo()の結果です。<icon/>と<icon />の両方に対応しています。要素を入れ子にする場合は、<link><strong>refund policy</strong></link>のように異なる名前を使い、両方のコールバックを指定してください。パーサーは、次に現れる名前の一致する終了タグを使います。同名のタグを繰り返し入れ子にする構造は、開始タグと終了タグが正しく対応するHTML構造としては扱えません。

文言だけでなく翻訳後のタグも確認する #

開始・終了タグのペアや自己終了タグに対応するコールバックがない場合、タグはそのままテキストとして残ります。対応する終了タグのない開始タグも同様です。これによりメッセージは描画できますが、読者には利用できるリンクではなく<link>が表示されることがあります。

実際のコールバックを使って、翻訳後のテンプレートをテストしてください。リンクのテキストとhrefを検証し、タグが欠けているケースも含めて、意図しないマークアップを開発中に確認できるようにしてください。描画テストに翻訳リクエストは必要ありません。

対応しているマークアップは名前付きタグであり、任意のHTMLではありません。属性は翻訳内に書かず、コールバックで指定してください。対応するタグがない場合の処理にdangerouslySetInnerHTMLを使うと、この役割分担が失われます。

リッチメッセージでは単純な値を使う #

リッチテキストでは、テキスト部分にある単純な{name}の値を置換します。l.textで使われる複雑なICUフォーマッターは実行しません。数量に応じた文法の切り替えには、複数形と選択分岐を使ってください。または、対応しているリッチテキスト表現で記述できる、文法的に完結したメッセージを軸に画面を構成してください。リッチテンプレート内にICUの複数形構文をそのまま記述しても、波括弧があるだけで複数形の処理が有効になるわけではありません。