Intl.NumberFormat を使用した数値のロケール固有フォーマット

数値の表示フォーマット(例:千位区切り、小数点以下の桁数制御、通貨記号の付与など)は、特に財務系の処理において頻繁に必要となります。近年の JavaScript 環境では、Intl.NumberFormat インターフェースおよび Number.prototype.toLocaleString メソッドを通じて、標準で多言語・多地域対応の書式化が可能になっています。

1. 基本構文と指定方法

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
  • locales(省略可):言語タグ(BCP 47 形式)である文字列または文字列の配列。例:"ja-JP", "en-US"。未指定または undefined の場合、実行環境の既定言語が使用されます。
  • options(省略可):書式化の詳細を指定するオブジェクト。内部的には Intl.NumberFormat コンストラクタと同一のパラメータを受け取ります。

BCP 47 ロケールタグの構成例
言語コード(ISO 639)+[-地域コード(ISO 3166-1 alpha-2)] の形式で記述されます:

  • 英語(アメリカ): en-US
  • 中国語(簡体字、中国): zh-CN
  • スペイン語(スペイン): es-ES
  • 日本語: ja または ja-JP

主なオプションプロパティ

プロパティ説明
style"decimal"(普通の数値), "percent", "currency", "unit" のいずれかを指定。既定は "decimal"
currency通貨書式にする場合の ISO 4217 通貨コード(例: "JPY", "USD")。
currencyDisplay通貨記号の表示形式("symbol", "code", "name", "narrowSymbol")。
useGrouping千位区切りを有効にするか(デフォルト: true)。
minimumFractionDigits最小小数桁数。不足分は 0 埋めされます。
maximumFractionDigits最大小数桁数。切り上げ・切り捨ての基準になります。
minimumIntegerDigits最小整数部桁数。不足分は先頭に 0 が挿入されます。
minimumSignificantDigits最小有効数字桁数(digits-based 表示向け)。
maximumSignificantDigits最大有効数字桁数。

また、unit オプションは style: "unit" 指定時にのみ使用可能で、以下の単位がサポートされています:

  • "meter", "kilometer", "inch", "foot", "mile", "celsius", "fahrenheit"
  • "hour", "minute", "second", "day", "week", "month", "year"
  • "byte", "kilobyte", "megabyte", "gigabyte", "terabyte"
  • "percent"style: "percent" 及び個別指定時の両方で使用可)など多数

2. 実践的な書式化例

// 通常の数値(ロケール依存)  
const value = 123456.65491;
console.log(value.toLocaleString());                    // en-US: 123,456.655
console.log(value.toLocaleString("de-DE"));             // de-DE: 123.456,655
console.log(value.toLocaleString("zh-Hans-CN"));        // zh-CN: 123,456.655
console.log(value.toLocaleString("ja-JP"));             // ja-JP: 123,456.655

// 千位区切りなし
console.log(value.toLocaleString(undefined, { useGrouping: false })); // 123456.655

// 現地の数字NM(例:中国語十進数字)
console.log(value.toLocaleString("zh-Hans-CN-u-nu-hanidec")); // 一二三,四五六.六五四

// 単位付きフォーマット  
console.log(value.toLocaleString("zh-CN", { style: "unit", unit: "mile" })); // 123,456.655 英里
console.log(value.toLocaleString("en-US", { style: "unit", unit: "celsius" })); // 123,456.655°C

// 通貨フォーマット(スタイル+通貨指定)  
console.log(value.toLocaleString("en-US", { style: "currency", currency: "USD" })); // $123,456.65
console.log(value.toLocaleString("zh-CN", { style: "currency", currency: "JPY" })); // ¥123,457
console.log(value.toLocaleString("fr-FR", { style: "currency", currency: "EUR" })); // 123 456,65 €
console.log(value.toLocaleString("de-DE", { style: "currency", currency: "EUR", currencyDisplay: "code" })); // 123.456,65 EUR

// 特殊表示(有効数字桁制御)
console.log((0.00123456).toLocaleString("en-US", { minimumSignificantDigits: 2, maximumSignificantDigits: 4 })); // 0.001235
console.log((12345.6789).toLocaleString("en-US", { minimumSignificantDigits: 3, maximumSignificantDigits: 5 })); // 12,346

// 小数点・整数部の桁調整  
const num = 42.5;
console.log(num.toLocaleString(undefined, { minimumFractionDigits: 3, maximumFractionDigits: 3 })); // 42.500
console.log(num.toLocaleString(undefined, { minimumIntegerDigits: 3 }));                            // 042.5

// 多言語フォールバック指定  
// アラビア語(エジプト)で表示 → 非対応なら英語(米国)へフォールバック
console.log(value.toLocaleString(["ar-EG", "en-US"])); // ١٢٣ ٤٥٦٫٦٥٥

3. MDN 提供の参考利用ケース

// ドイツ語(小数にコンマ、区切りにドット)
(123456.789).toLocaleString("de-DE"); // 123.456,789

// アラビア語(エジプト)におけるアラビア・インディック数字
(123456.789).toLocaleString("ar-EG"); // ١٢٣٤٥٦٫٧٨٩

// インド英語(ラク/クロール単位体系)
(123456.789).toLocaleString("en-IN"); // 1,23,456.789

// 中国語十進数字(漢数字)表記
(123456.789).toLocaleString("zh-Hans-CN-u-nu-hanidec"); // 一二三,四五六.七八九

// BCP 47 エクステンションキー "nu" を用いた明示的数字系统指定可能
// 具体例: "nu-hanidec", "nu-latn"

タグ: number-formatting locale Intl.NumberFormat BCP-47 currency-formatting

7月10日 18:54 投稿