Date.prototype.toLocaleString()

La méthode toLocaleString() renvoie une chaine de caractères représentant la date selon une locale. Les arguments locales et options permettent aux applications de définir le langage à utiliser pour les conventions de format et permettent de personnaliser le comportement de la fonction. Les anciennes implémentations ignorent ces arguments, la locale utilisée et le format de la chaine dépendent uniquement de l'implémentation.

Syntaxe

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

Paramètres

Voir le tableau de compatibilité des navigateurs afin de déterminer quels navigateurs respectent les arguments locales et options ainsi que l'exemple Vérifier le support des arguments locales et options qui permet de détecter cette fonctionnalité.

localesFacultatif

Ce paramètre optionnel est une chaine de caractères avec un identifiant de langue BCP 47, ou un tableau de ce type de chaine de caractères. Pour utiliser la locale par défaut du navigateur, on pourra omettre cet argument (ou passer la valeur undefined). Pour le format général et l'interprétation de l'argument locales, voir la page Intl. Les clefs d'extensions Unicode suivantes sont autorisées :

nu
Système de numérotation. Les valeurs possibles incluent : "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".
ca
Calendrier. Les valeurs possibles incluent : "buddhist", "chinese", "coptic", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc".
hc
Le type de cycle horaire à utiliser. Les valeurs possibles sont "h11", "h12", "h23", "h24".
options

Un objet avec certaines ou toutes les propriétés suivantes :

localeMatcher
L'algorithme de correspondance à utiliser pour la locale. Les valeurs possibles sont "lookup" et "best fit" ; le défaut est "best fit". Pour des informations sur cette option, voir la page Intl
timeZone
Le fuseau horaire à utiliser. La seule valeur que doivent reconnaitre les implémentations est "UTC" ; la valeur par défaut est le fuseau horaire du moteur JavaScript. Les implémentations peuvent aussi reconnaitre les noms de fuseau horaire de la base de données IANA de fuseaux horaires, tel que "Asia/Shanghai", "Asia/Kolkata", "America/New_York".
hour12
S'il faut utiliser le format horaire sur 12 heures (au lieu de celui-ci sur 24 heures). Les valeurs possibles sont true et false ; la valeur par défaut dépend de la locale. Cette option surcharge l'étiquette hc et/ou l'option hourCycle.
hourCycle
Le cycle horaire à utiliser. Les valeurs possibles sont "h11", "h12", "h23", "h24". Cette option surcharge l'étiquette hc mais sera remplacée par hour12 si cette dernière est présente.
formatMatcher
L'algorithme de correspondance à utiliser pour le formattage. Les valeurs possibles sont "basic" et "best fit" ; par défaut "best fit". Voir les paragraphes suivants pour des informations concernant l'usage de cette propriété.

Les propriétés suivantes décrivent les composants date-heure à utiliser pour le formattage de la sortie.  Les implémentations ont pour obligation de supporter au minimum les ensembles suivants :

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

Les implémentations peuvent supporter d'autres sous-ensembles, et les demandes seront évaluées face à toutes les combinaisons de sous-ensembles disponibles pour trouver la meilleure correspondance. Deux algorithmes sont disponibles pour cette évaluation et choisis par la propriété formatMatcher : un algorithme "basic" complètement spécifié et un algorithme "best fit" dépendant de l'implémentation.

weekday
La représentation du jour de la semaine. Les valeurs possibles sont :
  • "long" (par exemple Thursday)
  • "short" (par exemple Thu)
  • "narrow" (par exemple T). Deux jours de la semaines pourront partager la même représentation dans certaines locales (par exemple, en anglais Tuesday sera également représenté avec T en notation étroite).
era
La représentation de l'ère. Les valeurs possibles sont :
  • "long" (par exemple Anno Domini)
  • "short" (par exemple AD)
  • "narrow" (par exemple A)
year
La représentation de l'année. Les valeurs possibles sont :
  • "numeric" (par exemple 2012)
  • "2-digit" (par exemple 12)
month
La représentation du mois. Les valeurs possibles sont :
  • "numeric" (par exemple 2)
  • "2-digit" (par exemple 02)
  • "long" (par exemple March)
  • "short" (par exemple Mar)
  • "narrow" (par exemple M). Dans certaines locales, deux mois pourront partager la même représentation avec le style étroit (par exemple, May en anglais, sera également représenté avec M).
day
La représentation du jour. Les valeurs possibles sont :
  • "numeric" (par exemple 1)
  • "2-digit" (par exemple 01)
hour
La représentation de l'heure. Les valeurs possibles sont :
  • "numeric" (par exemple 1)
  • "2-digit" (par exemple 01)
minute
La représentation des minutes. Les valeurs possibles sont :
  • "numeric" (par exemple 1)
  • "2-digit" (par exemple 01)
second
La représentation des secondes. Les valeurs possibles sont :
  • "numeric" (par exemple 1)
  • "2-digit" (par exemple 01)
timeZoneName
La représentation du fuseau horaire. Les valeurs possibles sont :
  • "long" (par exemple British Summer Time)
  • "short" (par exemple GMT+1)

La valeur par défaut de chacun des composants de la date-heure vaut undefined, mais si les propriétés weekday, year, month, day, hour, minute, second sont toutes undefined,  alors  weekday, year, month, day, hour, minute et second sont supposés être "numeric".

Valeur de retour

Une chaîne de caractères représentant la date indiquée selon des conventions de locales spécifiques.

Exemples

Utiliser toLocaleString()

Voici un usage simple qui ne définit pas de locale : une chaine de caractères dans une locale et avec des options par défaut est renvoyée.

var date = new Date(Date.UTC(2014, 11, 21, 3, 0, 0));

// toLocaleString() sans argument, on utilise donc
// les valeurs par défaut (de l'implémentation)
// pour la locale, et le fuseau horaire
date.toLocaleString();
// → "21/12/2014 04:00:00" si exécuté dans une locale fr et le fuseau horaire CEST

Vérifier le support des arguments locales et options

Les arguments locales et options ne sont pas encore supportés par tous les navigateurs. Afin de vérifier si l'implementation utilisée les supporte, vous pouvez utiliser le pré-requis suivant : les locales incorrectes sont rejetées avec une exception RangeError :

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

Utiliser locales

Cet exemple montre quelques variations dues aux formats de dates localisés. Afin d'obtenir le langage utilisé au sein de l'interface utilisateur de votre application, vérifiez de bien fournir ce langage (et éventuellement des locales de recours) en utilisant l'argument locales :

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

// les formats qui suivent se basent sur le
// fuseau horaire CEST

l'anglais américain utilise l'ordre mois-jour-année
console.log(date.toLocaleString("en-US"));
// → "12/20/2012, 4:00:00 AM"

// l'anglais britannique utilise l'ordre jour-mois-année
console.log(date.toLocaleString("en-GB"));
// → "20/12/2012 04:00:00"

// le coréen utilise l'ordre année-mois-jour
console.log(date.toLocaleString("ko-KR"));
// → "2012. 12. 20. 오전 4:00:00"

// l'arabe, dans la plupart des pays arabophones, utilise les chiffres arabes
console.log(date.toLocaleString("ar-EG"));
// → "٢٠‏/١٢‏/٢٠١٢ ٤:٠٠:٠٠ ص"

// en ce qui concerne le japonais, les applications peuvent
// souhaiter utiliser le calendrier japonais
// pour lequel 2012 était l'année 24 de l'ère Heisei
console.log(date.toLocaleString("ja-JP-u-ca-japanese"));
// → "24/12/20 4:00:00"

// quand un langage non support est demandé (ex : le balinais)
// il est possible de fournir un langage de recours (ici l'indonésien)
console.log(date.toLocaleString(["ban", "id"]));
// → "20/12/2012 04.00.00"

Utiliser options

Les résultats fournis par toLocaleString() peuvent être personnalisés grâce à l'argument options :

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

// obtenir le jour de la semaine avec une date longue
var options = {weekday: "long", year: "numeric", month: "long", day: "numeric"};
console.log(date.toLocaleString("de-DE", options));
// → "Donnerstag, 20. Dezember 2012"

// une application peut vouloir utiliser UTC et le rendre visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleString("en-US", options));
// → "Thursday, December 20, 2012, GMT"

// parfois, même les USA ont besoin d'avoir une heure sur 24h
console.log(date.toLocaleString("en-US", {hour12: false}));
// → "12/19/2012, 19:00:00"

Comparaison des dates formatées et des valeurs statiques

La plupart du temps, le format renvoyé par toLocaleString() est cohérent. Toutefois, cela peut évoluer à l'avenir et n'est pas garanti pour l'ensemble des langues (de telles variations sont souhaitables et permises par la spécification). Ainsi, IE et Edge ajoutent des caractères de contrôle bidirectionnels autour des dates afin que le texte produit ait une directionalité cohérente avec le texte avec lequel elles seront concaténées.

Aussi, mieux vaut ne pas comparer un résultat fourni par format() avec une valeur statique :

"1.1.2019, 01:00:00" === new Date("2019-01-01T00:00:00.000000Z").toLocaleString();
// true pour Firefox et les autres
// false pour IE et Edge

Note : Voir aussi ce fil StackOverflow pour plus de détails et d'exemples.

Performance

Quand vous formatez d'importants volumes de dates, il est préférable de créer un objet Intl.DateTimeFormat et d'utiliser la fonction fournie via la propriété format.

Spécifications

Spécification État Commentaires
ECMAScript 1st Edition (ECMA-262) Standard Définition initiale. Implémentée avec JavaScript 1.0.
ECMAScript 5.1 (ECMA-262)
La définition de 'Date.prototype.toLocaleString' dans cette spécification.		 Standard
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'Date.prototype.toLocaleString' dans cette spécification.		 Standard
ECMAScript (ECMA-262)
La définition de 'Date.prototype.toLocaleString' dans cette spécification.		 Standard évolutif
ECMAScript Internationalization API 1.0 (ECMA-402)
La définition de 'Date.prototype.toLocaleString' dans cette spécification.		 Standard Définition des arguments locales et options.
ECMAScript Internationalization API 2.0 (ECMA-402)
La définition de 'Date.prototype.toLocaleString' dans cette spécification.		 Standard
ECMAScript Internationalization API (ECMA-402)
La définition de 'Date.prototype.toLocaleString' dans cette spécification.		 Standard évolutif

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung InternetNode.js
toLocaleStringChrome Support complet 1Edge Support complet 12Firefox Support complet 1IE Support complet 3Opera Support complet 3Safari Support complet 1WebView Android Support complet 1Chrome Android Support complet 18Firefox Android Support complet 4Opera Android Support complet 10.1Safari iOS Support complet 1Samsung Internet Android Support complet 1.0nodejs Support complet 0.1.100
IANA time zone names in timeZone optionChrome Support complet 24Edge Support complet 14Firefox Support complet 52IE Aucun support NonOpera Support complet 15Safari Support complet 6.1WebView Android Support complet 37Chrome Android Support complet 25Firefox Android Aucun support NonOpera Android Support complet 14Safari iOS Support complet 7Samsung Internet Android Support complet 1.5nodejs Support complet 0.12
localesChrome Support complet 24Edge Support complet 12Firefox Support complet 29IE Support complet 11Opera Support complet 15Safari Support complet 10WebView Android Aucun support NonChrome Android Support complet 26Firefox Android Support complet 56Opera Android Support complet 14Safari iOS Support complet 10Samsung Internet Android Support complet 1.5nodejs Support complet 13.0.0
Support complet 13.0.0
Support partiel 0.12
Notes
Notes Prior to Node.js 13.0.0, 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 Support complet 24Edge Support complet 12Firefox Support complet 29IE Support complet 11Opera Support complet 15Safari Support complet 10WebView Android Aucun support NonChrome Android Support complet 26Firefox Android Support complet 56Opera Android Support complet 14Safari iOS Support complet 10Samsung Internet Android Support complet 1.5nodejs Support complet 0.12

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Voir les notes d'implémentation.
Voir les notes d'implémentation.

Voir aussi

Sujets associés
  1. Objets standards
  2. Date
  3. Méthodes
    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]
  4. Héritage :
  5. Function
  6. Propriétés
    1. Function.arguments
    2. Function.arity
    3. Function.caller
    4. Function.displayName
    5. Function.length
    6. Function.name
  7. Méthodes
    1. Function.prototype.apply()
    2. Function.prototype.bind()
    3. Function.prototype.call()
    4. Function.prototype.isGenerator()
    5. Function.prototype.toSource()
    6. Function.prototype.toString()
  8. Object
  9. Propriétés
    1. Object.prototype.__count__
    2. Object.prototype.__noSuchMethod__
    3. Object.prototype.__parent__
    4. Object.prototype.__proto__
    5. Object.prototype.constructor
  10. Méthodes
    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()