ロケールに合わせて値を書式設定する

表示に必要な単位や時刻情報を指定し、ネイティブの Intl で数値、日付、リスト、テキストを書式設定します。

翻訳済みのメッセージにも、価格、日付、数量、リストなどの値が含まれます。Lingo オブジェクトは、カタログを検索せずに、現在のロケールに合わせてこれらの値を書式設定します。周囲のメッセージの表示にも同じオブジェクトを使うことで、メッセージと値に同じロケールを適用できます。

数値と数量 #

ts
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 に翻訳されることもありません。

日付、時刻、相対的な時間差 #

ts
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 データによって異なる場合があります。ハイドレーションでは、ロケールだけでなく、タイムスタンプ、タイムゾーン、相対時刻の基準も一致させてください。