メッセージとコンテキスト
ソースメッセージは全文を記述し、その意味を説明しましょう。変動する値は、メッセージの識別情報を変えずに挿入できます。
翻訳でも、言葉が表す操作や意味を保つには、十分な情報が必要です。ソーステキストは全文を記述し、contextでその用途を説明してください。名前や件数など、変動するデータはvaluesで渡します。
import { useLingo } from "@lingo.dev/react";
export function Greeting({ name }: { name: string }) {
const l = useLingo();
return (
<h1>
{l.text("Welcome back, {name}.", {
context: "Greeting at the top of the account dashboard",
values: { name },
})}
</h1>
);
}結果は文字列です。TextOptionsではcontext: stringが必須で、values?: Record<string, string | number>も指定できます。カタログには文のテンプレートが格納されます。翻訳では、文法に合わせて{name}の位置を変えられます。
曖昧なメッセージの意味を説明する #
「保存」は、フォームの送信を意味する場合も、記事のブックマークを意味する場合もあります。英語のソースが同じでも、コンテキストがあれば、次のように別々のメッセージとして扱えます。
import { computeKey } from "@lingo.dev/react";
const submitKey = computeKey("Save", "Submit changes to account settings");
const bookmarkKey = computeKey("Save", "Bookmark this article for later reading");キーが異なるため、翻訳者はそれぞれの操作に適した動詞を選べます。「ユーザーに表示されるテキスト」といったコンテキストでは、この曖昧さは解消できません。表現の選択に影響する操作、対象者、制約を記述してください。
抽出ツールは、この情報をカタログの@contextコメントに書き込みます。これは翻訳のための指針であり、画面に表示されるテキストではありません。共通して使う用語や指示、文体の要件はローカライゼーションエンジンの翻訳コンテキストにまとめ、メッセージ固有の意味は呼び出し箇所に記述してください。
メッセージの識別情報 #
computeKey(source: string, context?: string): stringは、ソースとコンテキストから8文字のキーを生成します。空でないコンテキストをヌル区切り文字でソースに連結し、結合した入力をUnicode NFCに正規化して、そのUTF-8バイト列をハッシュ化します。
Unicodeで正準等価な表記には、同じキーが使われます。文言、句読点、大文字と小文字、空白、コンテキストを変更すると、新しいキーが生成される場合があります。値はハッシュの計算に含まれないため、挨拶に使う名前が変わっても、同じメッセージ項目が使われます。
ソースやコンテキストを変更したら、再度抽出し、新しい項目と参照されなくなった項目を確認してください。意味を確認せずに翻訳を新しいキーにコピーすると、ソースの変更で置き換えるはずだった表現が、そのまま残るおそれがあります。ハッシュ値の種類は有限です。抽出ツールは、収集したメッセージ間での衝突を検出します。
抽出できる形で呼び出す #
l.text(...)のような呼び出しでは、ソース文字列とコンテキストをリテラルで指定してください。実行時には計算で生成した文字列も受け取れますが、抽出ツールは、プログラムが組み立てる可能性のあるすべての文字列を推測できません。レシーバーにはl、またはuseLingoかcreateLingoから作成したサポート対象の変数を使ってください。認識される形式については、抽出のリファレンスを参照してください。
"Welcome, " + nameのようなソース文字列を生成するのではなく、変動するデータにはプレースホルダーを使ってください。固定のテンプレートなら抽出でき、意味ごとに一度翻訳すれば、値を変えて再利用できます。
値の埋め込みとICU #
単純なプレースホルダーには、{name}のような名前を使います。渡した値はテキストとして扱われます。対応する値がない場合、単純なプレースホルダーはそのまま表示されます。valuesオブジェクトを省略すると、値を埋め込まずに、選択されたテンプレートが返されます。
数量やカテゴリによって文法が変わる場合に対応できるよう、テキストフォーマッターはintl-messageformatを通じて複雑なICUパターンをサポートしています。
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en");
const label = l.text("{count, plural, =0 {No files} one {# file} other {# files}}", {
context: "Number of files attached to a message",
values: { count: 0 },
});この例ではNo filesが返されます。明示的な=0分岐により、ゼロをロケールの通常の複数形カテゴリと区別します。選択されたテンプレートに必要な引数は、すべて渡してください。複雑なICUの解析や書式設定に失敗した場合、実行時にはそのテンプレートが返され、重複を除いた開発時エラーが報告されます。不正な形式の翻訳を、ソースから新たに書式設定した結果に置き換えることはありません。
複数形と選択では、選択肢をそれぞれ完全な形で用意するためのヘルパーを提供しています。リッチテキストでは、専用の名前付きタグパーサーを通じてReact要素を挿入します。リッチテキストのテンプレートに複雑なICU式を混在させず、用途に合った形式を使ってください。