ロケールに合わせて値を書式設定する
表示に必要な単位や時刻情報を指定し、ネイティブの Intl で数値、日付、リスト、テキストを書式設定します。
翻訳済みのメッセージにも、価格、日付、数量、リストなどの値が含まれます。Lingo オブジェクトは、カタログを検索せずに、現在のロケールに合わせてこれらの値を書式設定します。周囲のメッセージの表示にも同じオブジェクトを使うことで、メッセージと値に同じロケールを適用できます。
数値と数量 #
import { createLingo } from "@lingo.dev/react";
const l = createLingo("en-US");
const price = l.currency(29.99, "USD");
const completion = l.percent(0.125, { maximumFractionDigits: 1 });
const temperature = l.unit(32, "celsius", { unitDisplay: "long" });価格の書式設定では、指定された米ドルの金額を整えるだけで、通貨換算は行いません。パーセントの入力値は比率として扱われるため、0.125 は 12.5% と表示され、12.5 を指定すると 1250% を意味します。同様に、単位ヘルパーも指定された摂氏の値に単位を付けるだけで、換算は行いません。
| メソッド | 値の後に指定する引数 |
|---|---|
num(value: number) | Intl.NumberFormatOptions(省略可能)。 |
currency(value: number, currency: string) | 通貨コード、続いて数値書式オプション(省略可能)。 |
percent(value: number) | 数値書式オプション(省略可能)。 |
unit(value: number, unit: string) | 単位識別子、続いて数値書式オプション(省略可能)。 |
compact(value: number) | 数値書式オプション(省略可能)。 |
fileSize(bytes: number) | オプションなし。 |
すべてのメソッドが文字列を返します。通貨、パーセント、単位の各メソッドでは、名前に対応するスタイルが必ず適用されます。compact では、他のオプションを適用した後に、必ずコンパクト表記が適用されます。
fileSize は 1024 の累乗で値を割り、固定ラベルの B、KB、MB、GB、TB、PB を使用します。数値はロケールに合わせて書式設定され、バイトは小数桁なし、それより大きい単位は小数点以下最大 1 桁で表示されます。1024 は 1 KB に、ゼロは 0 B になります。バイト数にはゼロ以上の整数を指定してください。負の値や小数を含むバイト数については、実用的な表示方針が定められていません。また、GB などのラベルがフランス語の Go に翻訳されることもありません。
日付、時刻、相対的な時間差 #
const instant = new Date("2026-10-10T12:00:00Z");
const timestamp = l.datetime(instant, { timeZone: "UTC" });
const date = l.date(instant, {
year: "numeric",
month: "2-digit",
day: "2-digit",
timeZone: "UTC",
});
const age = l.relative(-3, "day", { numeric: "auto" });これらの呼び出しでは、前の例の l を使用します。date、time、datetime は Date | number を受け取り、その後に任意で Intl.DateTimeFormatOptions を指定できます。数値のタイムスタンプの単位はミリ秒で、ユニックス時刻の秒ではありません。既定の書式は、それぞれ中程度の長さの日付、短い時刻、その両方です。
year や hour などの個別フィールドを指定すると、既定のスタイルは適用されなくなります。スタイルオプションを明示すれば既定値を上書きできますが、スタイルと個別フィールドを併用できない組み合わせでは、ネイティブの Intl が例外を投げることがあります。サーバーとブラウザで同じ日付を表示する必要がある場合は、タイムゾーンを設定してください。
relative(value, unit, options?) は、符号付きの数値、Intl.RelativeTimeFormatUnit、省略可能な Intl.RelativeTimeFormatOptions を受け取り、指定された時間差を書式設定します。基準時点との差はアプリケーションのコードで計算し、必要に応じて更新してください。このメソッドは現在時刻を取得せず、更新のスケジュール設定も行いません。
リストとテキストの操作 #
| メソッド | 結果と動作 |
|---|---|
list(items: string[], options?: Intl.ListFormatOptions) | 選択済みのラベルを連結した文字列。既定では接続詞で結びます。 |
displayName(code, type) | ローカライズされた名前、または undefined。型は language、region、script、currency のいずれかです。ネイティブのフォールバック処理により、コード自体が返されることがあります。 |
sort(items: string[], options?: Intl.CollatorOptions) | ロケールの照合順序で並べ替えた新しい配列。入力の配列は変更されません。 |
segment(text, granularity?) | 文字列を分割したセグメント。既定では grapheme を使用し、word または sentence も指定できます。単語モードでは空白のセグメントも含まれます。 |
displayName はネイティブのエラーを捕捉し、undefined を返します。他のメソッドは、このエラー捕捉を行いません。ロケールコードとオプションは、アプリケーションに渡される時点で検証してください。
サポート対象の実行環境に合わせる #
これらのヘルパーは、ネイティブの NumberFormat、DateTimeFormat、RelativeTimeFormat、ListFormat、DisplayNames、Collator、Segmenter に処理を委ねます。このパッケージは、不足しているネイティブ API を補ったり、すべての実行環境のロケールデータを提供したりするものではありません。
サポート対象のサーバーとブラウザで、代表的な値をテストしてください。句読点や表記の慣習は、ICU データによって異なる場合があります。ハイドレーションでは、ロケールだけでなく、タイムスタンプ、タイムゾーン、相対時刻の基準も一致させてください。