Number : méthode toLocaleString()

Exemple interactif

function eArabic(x) {
  return x.toLocaleString("ar-EG");
}

console.log(eArabic(123456.789));
// Sortie attendue : "١٢٣٬٤٥٦٫٧٨٩"

console.log(eArabic("123456.789"));
// Sortie attendue : "123456.789"

console.log(eArabic(NaN));
// Sortie attendue : "ليس رقم"

Syntaxe

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Paramètres

Les paramètres locales et options permettent à l'application de définir les options de formatage selon la langue utilisée.

Dans les implémentations qui prennent en charge l'API Intl.NumberFormat, ces paramètres correspondent exactement aux paramètres du constructeur Intl.NumberFormat(). Les implémentations sans prise en charge de Intl.NumberFormat sont invitées à ignorer les deux paramètres, ce qui rend la locale utilisée et la forme de la chaîne de caractères retournée entièrement dépendantes de l'implémentation.

locales Facultatif

Une chaîne de caractères avec une balise de langue BCP 47, ou un tableau de telles chaînes de caractères. Correspond au paramètre locales du constructeur Intl.NumberFormat().

Dans les implémentations sans prise en charge de Intl.NumberFormat, ce paramètre est ignoré et la locale de l'hôte est généralement utilisée.

options Facultatif

Un objet ajustant le format de sortie. Correspond au paramètre options du constructeur Intl.NumberFormat().

Dans les implémentations sans prise en charge de Intl.NumberFormat, ce paramètre est ignoré.

Voir le constructeur Intl.NumberFormat() pour plus de détails sur ces paramètres et sur la manière de les utiliser.

Valeur de retour

Une chaîne de caractères représentant le nombre donné en tenant compte des conventions spécifiques à la langue.

Dans les implémentations qui prennent en charge l'API Intl.NumberFormat, cela équivaut à new Intl.NumberFormat(locales, options).format(number).

Exemples

Utiliser toLocaleString()

Une utilisation de cette méthode sans définition de locale retourne une chaîne de caractères formatée dans la locale par défaut et avec les options par défaut.

const nombre = 3500;

console.log(nombre.toLocaleString()); // Affiche "3 500" pour la locale française

Vérifier la prise en charge des arguments locales et options

Les paramètres locales et options peuvent ne pas être pris en charge dans toutes les implémentations, parce que la prise en charge pour les API d'internationalisation est optionnelle et certains systèmes n'ont pas les données nécessaires. Pour les implémentations sans prise en charge de l'internationalisation, toLocaleString() utilise toujours la locale du système, ce qui peut ne pas être ce que vous souhaitez. Comme toute implémentation qui prend en charge les paramètres locales et options doit prendre en charge l'API Intl, vous pouvez vérifier l'existence de cette dernière pour en vérifier la prise en charge :

function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.NumberFormat === "function"
  );
}

Utiliser locales

Cet exemple illustre les variations possibles entre les différents formats localisés. Afin que le format de langue utilisé soit celui de la personne qui utilise votre site ou votre application, assurez-vous de fournir la langue utilisée (ainsi que des langues de secours) en utilisant l'argument locales :

const nombre = 123456.789;

// Pour la locale allemande, on utilise un point comme séparateur
// pour les milliers et une virgule comme séparateur décimal
console.log(nombre.toLocaleString("de-DE"));
// 123.456,789

// Les locales arabes, dans la plupart des pays arabophones, utilisent
// les chiffres arabes
console.log(nombre.toLocaleString("ar-EG"));
// ١٢٣٤٥٦٫٧٨٩

// En Inde, on utilise des séparateurs de milliers/lakh/crore
console.log(nombre.toLocaleString("en-IN"));
// 1,23,456.789

// La clé d'extension nu indique un système numérique, ici le système chinois décimal
console.log(nombre.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// 一二三,四五六.七八九

// quand on souhaite utiliser un langage qui n'est pas pris en charge, on peut
// inclure un langage de secours. Exemple ici avec le balinais et l'indonésien
console.log(nombre.toLocaleString(["ban", "id"]));
// 123.456,789

Utiliser options

Les résultats fournis par toLocaleString peuvent être adaptés en utilisant l'argument options :

const nombre = 123456.789;

// on formate selon une devise
console.log(
  nombre.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// 123.456,79 €

// le yen japonais ne possède pas de centimes
console.log(
  nombre.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// ￥123,457

// on se limite à trois chiffres significatifs
console.log(nombre.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// 1,23,000

// on utilise la langue du système pour la mise en
// forme des nombres
const num = 30000.65;
console.log(
  num.toLocaleString(undefined, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  }),
);
// "30,000.65" quand l'anglais est la langue par défaut
// "30.000,65" quand l'allemand est la langue par défaut
// "30 000,65" quand le français est la langue par défaut

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'objet Intl.NumberFormat
• La méthode Number.prototype.toString()