数値の表示フォーマット(例:千位区切り、小数点以下の桁数制御、通貨記号の付与など)は、特に財務系の処理において頻繁に必要となります。近年の 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"