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

構文

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

引数

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

locales

任意。BCP47 言語タグの文字列、または、そのような文字列の配列。locales 引数の一般的な形式と解釈は、Intl page をご覧ください。次の Unicode 拡張キーが許可されています:

nu
番号方式。使用できる値は以下のとおりです: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt"
ca
カレンダー。使用できる値は以下のとおりです。: "buddhist", "chinese", "coptic", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc"
options

任意。以下のプロパティの一部またはすべてを持つオブジェクト:

localeMatcher
使用するロケールマッチングアルゴリズム。可能な値は "lookup""best fit" です。デフォルトは "best fit" です。このオプションについての詳細は、Intl page をご覧ください。
timeZone
使用するタイムゾーン。実装が認識しなければならない唯一の値は "UTC" です。デフォルトは、実行時のデフォルトのタイムゾーンです。実装は、また、"Asia/Shanghai", "Asia/Kolkata", "America/New_York" のような IANA time zone database のタイムゾーン名を認識できます。
hour12
12 時間表示を使用するかどうか (反対は 24 時間表示)。可能な値は truefalse です。デフォルトはロケール依存です。
formatMatcher
使用するフォーマットマッチングアルゴリズム。可能な値は "basic""best fit" です。デフォルトは "best fit" です。このプロパティの使用方法については、以下の項を参照してください。

次のプロパティは、日付·時刻のコンポーネントやそれらの所望の表現をフォーマットされた出力で使用するように記述します。実装は、少なくとも以下のサブセットをサポートするために必要です:

  • weekday, year, month, day, hour, minute, second
  • weekday, year, month, day
  • year, month, day
  • year, month
  • month, day
  • hour, minute, second
  • hour, minute

実装は、他のサブセットもサポートし、要求は、ベストマッチを見つけるために、すべての利用可能なサブセットの表現の組み合わせに対してネゴシエートされます。二つのアルゴリズムがこのネゴシエートに対して利用可能で、formatMatcher プロパティによって選択されます: fully specified "basic" algorithm"best fit" アルゴリズムに依存した実装。

weekday
平日の表現。可能な値は、"narrow", "short", "long" です。
era
時代の表現。可能な値は "narrow", "short", "long" です。
year
今年の表現。可能な値は "numeric", "2-digit" です。
month
月の表現。可能な値は "numeric", "2-digit", "narrow", "short", "long" です。
day
日の表現。可能な値は "numeric", "2-digit" です。
hour
時間の表現。可能な値は "numeric", "2-digit" です。
minute
分の表現。可能な値は "numeric", "2-digit" です。
second
秒の表現。可能な値は "numeric", "2-digit" です。
timeZoneName
タイムゾーン名の表現。可能な値は "short", "long" です。

各日時コンポーネントのプロパティのデフォルト値は、undefinedです。ただし、weekday および yearmonthdayhourminutesecond プロパティがすべて undefined のときは、yearmonthdayhourminutesecond"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 ロケールで実行した場合

localesoptions がサポートされているか確認する

localesoptions は、まだすべてのブラウザでサポートされていません。これらが実装されているかどうかは、不適切な言語タグを与えて 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 の定義
ドラフト  

ブラウザー実装状況

機能ChromeEdgeFirefoxInternet ExplorerOperaSafari
基本対応 あり あり1 あり あり あり
locales24 ?29111510
options24 ?29111510
IANA time zone names in timeZone option24 ?52 ? ? ?
機能Android webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
基本対応 あり あり あり4 あり あり あり
locales なし26 ?56 なし10 あり
options なし26 ?56 なし10 あり
IANA time zone names in timeZone option ? ? ? なし ? ? ?

関連情報

ドキュメントのタグと貢献者

このページの貢献者: sutara79, Marsf, shide55
最終更新者: sutara79,