Date.prototype.toLocaleString()

toLocaleString() メソッドは、言語に合わせた日時の文字列を返します。新しい locales 引数と options 引数により、アプリケーションは、使用される書式変換の言語の指定や、関数の振る舞いのカスタマイズができます。古い実装のアプリケーションは、locales 引数と options 引数を無視します。使用されるロケールや返される文字列の書式は、完全に実装依存です。

構文

dateObj.toLocaleString([locales[, options]])

引数

どのブラウザが locales と options をサポートしているのかは、ブラウザー実装状況 をご覧ください。実際に機能が使用できるかを確認するには、locales と options がサポートされているか確認する をご覧ください。

各日時コンポーネントのプロパティのデフォルト値は、undefinedです。ただし、weekday および year、month、day、hour、minute、second プロパティがすべて undefined のときは、year、month、day、hour、minute、second は "numeric" とみなされます。

戻り値

言語特有の規則に合わせた日付を表す文字列。

例

toLocaleString() を使う

ロケールを指定しない基本的な使い方では、デフォルトのロケールとデフォルトのオプションによる書式の文字列が返されます。

var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleString() メソッドに引数を与えなければ実装に依存し、
// デフォルトのロケールとタイムゾーンを返す
console.log(date.toLocaleString());
// → "12/11/2012, 7:00:00 PM" : アメリカ/ロサンゼルスのタイムゾーンの en-US ロケールで実行した場合

locales と options がサポートされているか確認する

locales と options は、まだすべてのブラウザでサポートされていません。これらが実装されているかどうかは、不適切な言語タグを与えて RangeError 例外で拒否されるかどうかで確かめられます:

function toLocaleStringSupportsLocales() {
  try {
    new Date().toLocaleString('i');
  } catch (e) {
    return e instanceof RangeError;
  }
  return false;
}

locales を使う

この例では、国ごとに異なる日付書式を示します。ご使用のアプリケーションのユーザインターフェースで使用される言語の書式を得るには、locales でその言語 (あるいはフォールバック先の言語) を指定してください:

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 以下の書式はその地域のタイムゾーンとロケールを想定
// 米国のアメリカ大陸/ロサンゼルス

// 米国英語は月-日-年の順で AM/PM 表記の 12 時間制
console.log(date.toLocaleString('en-US'));
// → "12/19/2012, 7:00:00 PM"

// 英国英語は日-月-年の順で AM/PM 表記なしの 24 時間制
console.log(date.toLocaleString('en-GB'));
// → "20/12/2012 03:00:00"

// 韓国は年-月-日の順で AM/PM 表記の 12 時間制
console.log(date.toLocaleString('ko-KR'));
// → "2012. 12. 20. 오후 12:00:00"

// 多くのアラビア語圏ではアラビア数字を使用
console.log(date.toLocaleString('ar-EG'));
// → "٢٠‏/١٢‏/٢٠١٢ ٥:٠٠:٠٠ ص"

// 日本のアプリケーションでは元号を用いることがある
// 2012 年は平成 24 年
console.log(date.toLocaleString('ja-JP-u-ca-japanese'));
// → "24/12/20 12:00:00"

// サポートされない可能性のある言語を要求した場合、
// ここではバリとし、フォールバック言語にインドネシア
console.log(date.toLocaleString(['ban', 'id']));
// → "20/12/2012 11.00.00"

options を使う

toLocaleString() メソッドから得られる結果は、options でカスタマイズできます:

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 曜日を加えて月とともに長い書式で表す
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
console.log(date.toLocaleString('de-DE', options));
// → "Donnerstag, 20. Dezember 2012"

// アプリケーションで UTC を用いてそれを示したい場合
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(date.toLocaleString('en-US', options));
// → "Thursday, December 20, 2012, GMT"

// 米国でも 24 時間制を使うことがある
console.log(date.toLocaleString('en-US', { hour12: false }));
// → "12/19/2012, 19:00:00"

性能

数多くの日付の書式を処理したいときは、Intl.DateTimeFormat オブジェクトを作成し、その format プロパティが提供する関数を用いるのがよいでしょう。

仕様

仕様書 策定状況 コメント
ECMAScript 1st Edition (ECMA-262) 標準 初期定義。JavaScript 1.0 で実装
ECMAScript 5.1 (ECMA-262)
Date.prototype.toLocaleString の定義		 標準  
ECMAScript 2015 (6th Edition, ECMA-262)
Date.prototype.toLocaleString の定義		 標準  
ECMAScript Latest Draft (ECMA-262)
Date.prototype.toLocaleString の定義		 ドラフト  
ECMAScript Internationalization API 1.0 (ECMA-402)
Date.prototype.toLocaleString の定義		 標準 locales および options 引数を定義
ECMAScript Internationalization API 2.0 (ECMA-402)
Date.prototype.toLocaleString の定義		 標準  
ECMAScript Internationalization API 4.0 (ECMA-402)
Date.prototype.toLocaleString の定義		 ドラフト  

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイルサーバー
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung InternetNode.js
toLocaleStringChrome 完全対応 1Edge 完全対応 12Firefox 完全対応 1IE 完全対応 3Opera 完全対応 ありSafari 完全対応 ありWebView Android 完全対応 1Chrome Android 完全対応 18Firefox Android 完全対応 4Opera Android 完全対応 ありSafari iOS 完全対応 ありSamsung Internet Android 完全対応 1.0nodejs 完全対応 あり
IANA time zone names in timeZone optionChrome 完全対応 24Edge 完全対応 14Firefox 完全対応 52IE 未対応 なしOpera 完全対応 15Safari ? WebView Android 完全対応 37Chrome Android 完全対応 25Firefox Android 未対応 なしOpera Android ? Safari iOS ? Samsung Internet Android 完全対応 1.5nodejs 完全対応 あり
localesChrome 完全対応 24Edge 完全対応 12Firefox 完全対応 29IE 完全対応 11Opera 完全対応 15Safari 完全対応 10WebView Android 未対応 なしChrome Android 完全対応 26Firefox Android 完全対応 56Opera Android 完全対応 14Safari iOS 完全対応 10Samsung Internet Android 完全対応 1.5nodejs 完全対応 0.12
補足
完全対応 0.12
補足
補足 Prior to NodeJS 13, only the locale data for en-us is available by default. When other English locales are specified, the function silently falls back to en-us. When other languages are specified, it throws a RangeError. In order to make full ICU (locale) data available for versions prior to 13, see docs on the --with-full-icu= flag and how to provide the data.
optionsChrome 完全対応 24Edge 完全対応 12Firefox 完全対応 29IE 完全対応 11Opera 完全対応 15Safari 完全対応 10WebView Android 未対応 なしChrome Android 完全対応 26Firefox Android 完全対応 56Opera Android 完全対応 14Safari iOS 完全対応 10Samsung Internet Android 完全対応 1.5nodejs 完全対応 あり

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
実装ノートを参照してください。
実装ノートを参照してください。

関連情報

関連トピック
  1. Standard built-in objects
  2. Date
  3. プロパティ
    1. Date.prototype
  4. メソッド
    1. Date.UTC()
    2. Date.now()
    3. Date.parse()
    4. Date.prototype.getDate()
    5. Date.prototype.getDay()
    6. Date.prototype.getFullYear()
    7. Date.prototype.getHours()
    8. Date.prototype.getMilliseconds()
    9. Date.prototype.getMinutes()
    10. Date.prototype.getMonth()
    11. Date.prototype.getSeconds()
    12. Date.prototype.getTime()
    13. Date.prototype.getTimezoneOffset()
    14. Date.prototype.getUTCDate()
    15. Date.prototype.getUTCDay()
    16. Date.prototype.getUTCFullYear()
    17. Date.prototype.getUTCHours()
    18. Date.prototype.getUTCMilliseconds()
    19. Date.prototype.getUTCMinutes()
    20. Date.prototype.getUTCMonth()
    21. Date.prototype.getUTCSeconds()
    22. Date.prototype.getYear()
    23. Date.prototype.setDate()
    24. Date.prototype.setFullYear()
    25. Date.prototype.setHours()
    26. Date.prototype.setMilliseconds()
    27. Date.prototype.setMinutes()
    28. Date.prototype.setMonth()
    29. Date.prototype.setSeconds()
    30. Date.prototype.setTime()
    31. Date.prototype.setUTCDate()
    32. Date.prototype.setUTCFullYear()
    33. Date.prototype.setUTCHours()
    34. Date.prototype.setUTCMilliseconds()
    35. Date.prototype.setUTCMinutes()
    36. Date.prototype.setUTCMonth()
    37. Date.prototype.setUTCSeconds()
    38. Date.prototype.setYear()
    39. Date.prototype.toDateString()
    40. Date.prototype.toGMTString()
    41. Date.prototype.toISOString()
    42. Date.prototype.toJSON()
    43. Date.prototype.toLocaleDateString()
    44. Date.prototype.toLocaleFormat()
    45. Date.prototype.toLocaleString()
    46. Date.prototype.toLocaleTimeString()
    47. Date.prototype.toSource()
    48. Date.prototype.toString()
    49. Date.prototype.toTimeString()
    50. Date.prototype.toUTCString()
    51. Date.prototype.valueOf()
    52. Date.prototype[@@toPrimitive]
  5. 継承
  6. Function
  7. プロパティ
    1. Function.arguments
    2. Function.arity
    3. Function.caller
    4. Function.displayName
    5. Function.length
    6. Function.name
    7. Function.prototype
  8. メソッド
    1. Function.prototype.apply()
    2. Function.prototype.bind()
    3. Function.prototype.call()
    4. Function.prototype.isGenerator()
    5. Function.prototype.toSource()
    6. Function.prototype.toString()
  9. Object
  10. プロパティ
    1. Object.prototype.__count__
    2. Object.prototype.__noSuchMethod__
    3. Object.prototype.__parent__
    4. Object.prototype.__proto__
    5. Object.prototype.constructor
  11. メソッド
    1. Object.prototype.__defineGetter__()
    2. Object.prototype.__defineSetter__()
    3. Object.prototype.__lookupGetter__()
    4. Object.prototype.__lookupSetter__()
    5. Object.prototype.hasOwnProperty()
    6. Object.prototype.isPrototypeOf()
    7. Object.prototype.propertyIsEnumerable()
    8. Object.prototype.toLocaleString()
    9. Object.prototype.toSource()
    10. Object.prototype.toString()
    11. Object.prototype.unwatch()
    12. Object.prototype.valueOf()
    13. Object.prototype.watch()
    14. Object.setPrototypeOf()