Comment formater les dates dans différents systèmes de calendrier ?

Introduction

La plupart des développeurs supposent que les dates fonctionnent de la même manière partout. Vous créez un objet Date pour le 15 mars 2025, vous le formatez et vous l'affichez aux utilisateurs. Cependant, cette supposition s'effondre lorsque vos utilisateurs suivent différents systèmes de calendrier.

Dans de nombreuses cultures, la date du 15 mars 2025 dans le calendrier grégorien a une représentation complètement différente. Pour les utilisateurs suivant le calendrier islamique, ce même moment se produit le 16 Ramadan 1447. Pour les utilisateurs du calendrier hébraïque, il tombe le 14 Adar II 5785. Pour les utilisateurs japonais dans des contextes officiels, il apparaît comme Reiwa 7, 15 mars.

Les systèmes de calendrier déterminent comment les sociétés comptent le temps. Ils définissent quand les années commencent, comment les mois sont organisés et comment les dates sont numérotées. L'API Intl.DateTimeFormat de JavaScript prend en charge plus de 17 systèmes de calendrier différents, vous permettant d'afficher les dates selon le contexte culturel et religieux de chaque utilisateur.

Cette leçon explique ce que sont les systèmes de calendrier, pourquoi ils existent et comment formater les dates en utilisant différents systèmes de calendrier en JavaScript.

Que sont les systèmes de calendrier

Un système de calendrier définit les règles d'organisation et de comptage du temps. Chaque système établit quand l'année commence, combien de mois existent, comment les jours sont numérotés et quelle époque sert de point de départ pour la numérotation des années.

Le calendrier grégorien, largement utilisé dans les contextes internationaux, compte les années à partir de la naissance estimée de Jésus-Christ. Il utilise 12 mois d'une durée allant de 28 à 31 jours, créant une année de 365 jours avec des années bissextiles tous les quatre ans.

D'autres systèmes de calendrier utilisent des structures et des points de départ différents. Le calendrier islamique utilise 12 mois lunaires totalisant 354 ou 355 jours par an. Le calendrier hébraïque combine des mois lunaires avec un alignement sur l'année solaire. Le calendrier japonais utilise des noms d'ère qui changent avec le règne de chaque empereur.

Ces systèmes existent parce que différentes cultures ont développé leurs propres façons de suivre le temps en fonction de la signification religieuse, des observations astronomiques et des événements historiques. De nombreuses cultures continuent d'utiliser des calendriers traditionnels parallèlement au calendrier grégorien pour les observances religieuses, les documents officiels et les événements culturels.

Pourquoi les systèmes de calendrier sont importants pour les applications

Les applications destinées aux utilisateurs de différentes origines culturelles doivent afficher les dates dans des formats que ces utilisateurs comprennent et auxquels ils s'attendent. Une application de temps de prière pour les utilisateurs musulmans devrait afficher les dates selon le calendrier islamique. Une application pour les observances religieuses juives nécessite des dates du calendrier hébraïque. Les applications gouvernementales japonaises exigent un formatage selon l'ère japonaise.

L'utilisation d'un système de calendrier inapproprié crée de la confusion et peut rendre votre application inutilisable pour son public cible. Afficher les dates des fêtes islamiques dans le calendrier grégorien oblige les utilisateurs à convertir manuellement les dates. Montrer les événements du calendrier hébraïque au format grégorien obscurcit la signification religieuse de ces dates.

Le même objet Date représente le même moment dans le temps quel que soit le système de calendrier. Ce qui change, c'est la façon dont vous formatez ce moment pour l'affichage. JavaScript vous permet de formater n'importe quelle date dans n'importe quel système de calendrier pris en charge sans logique de conversion complexe.

Utilisation de l'option calendar

Le constructeur Intl.DateTimeFormat accepte une option calendar qui spécifie quel système de calendrier utiliser lors du formatage des dates. Passez l'identifiant du calendrier comme valeur de chaîne.

const date = new Date('2025-03-15');

const gregorianFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'gregory',
  dateStyle: 'long'
});

const islamicFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic',
  dateStyle: 'long'
});

console.log(gregorianFormatter.format(date));
// Résultat : "March 15, 2025"

console.log(islamicFormatter.format(date));
// Résultat : "Ramadan 16, 1447 AH"

Le même objet Date produit différentes chaînes formatées selon le système de calendrier. Le calendrier grégorien affiche le 15 mars 2025. Le calendrier islamique affiche le 16 Ramadan 1447 AH.

L'option calendar fonctionne indépendamment de la locale. Vous pouvez formater les dates islamiques en anglais, arabe, français ou toute autre langue en combinant l'option calendar avec la locale appropriée.

const date = new Date('2025-03-15');

const arabicFormatter = new Intl.DateTimeFormat('ar-SA', {
  calendar: 'islamic',
  dateStyle: 'long'
});

const englishFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic',
  dateStyle: 'long'
});

console.log(arabicFormatter.format(date));
// Résultat : "١٦ رمضان ١٤٤٧ هـ"

console.log(englishFormatter.format(date));
// Résultat : "Ramadan 16, 1447 AH"

Le système de calendrier détermine quelle date afficher, tandis que la locale détermine la langue et les conventions de formatage.

Formatage des dates avec le calendrier islamique

Le calendrier islamique est un calendrier lunaire contenant 12 mois de 29 ou 30 jours. Une année lunaire complète compte environ 354 jours, soit 10 à 11 jours de moins que l'année grégorienne solaire. Cela fait que les dates islamiques reculent progressivement dans le calendrier grégorien au fil du temps.

JavaScript prend en charge plusieurs variantes du calendrier islamique. L'identifiant islamic utilise un calcul basé sur un algorithme. L'identifiant islamic-umalqura utilise le calendrier Umm al-Qura utilisé en Arabie Saoudite. L'identifiant islamic-civil utilise un calcul tabulaire prévisible.

const date = new Date('2025-03-15');

const islamicFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

const umalquraFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic-umalqura',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(islamicFormatter.format(date));
// Output: "Ramadan 16, 1447 AH"

console.log(umalquraFormatter.format(date));
// Output: "Ramadan 16, 1447 AH"

Pour la plupart des applications destinées aux utilisateurs musulmans, n'importe laquelle de ces variantes du calendrier islamique fonctionne correctement. Les différences entre elles sont minimes et importent principalement pour déterminer les dates exactes des observances religieuses.

Formatage des dates avec le calendrier hébraïque

Le calendrier hébraïque est un calendrier luni-solaire utilisé pour les observances religieuses juives. Il synchronise les mois lunaires avec l'année solaire en ajoutant un mois intercalaire certaines années. Cela permet de maintenir l'alignement des fêtes avec les saisons.

const date = new Date('2025-03-15');

const hebrewFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'hebrew',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(hebrewFormatter.format(date));
// Output: "14 Adar II 5785"

Le calendrier hébraïque utilise des noms de mois hébreux comme Nissan, Iyar, Sivan et Tamouz. Dans les années bissextiles, le calendrier inclut Adar I et Adar II. Le décompte des années représente les années écoulées depuis la création selon la tradition juive.

Vous pouvez formater les dates hébraïques en langue hébraïque pour les locuteurs natifs.

const date = new Date('2025-03-15');

const hebrewFormatter = new Intl.DateTimeFormat('he-IL', {
  calendar: 'hebrew',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(hebrewFormatter.format(date));
// Output: "י״ד באדר ב׳ ה׳תשפ״ה"

La sortie en langue hébraïque utilise des lettres hébraïques pour les nombres et l'écriture hébraïque pour les noms des mois.

Formatage des dates avec le calendrier japonais

Le calendrier japonais utilise des noms d'ères basés sur l'empereur régnant. L'ère actuelle, Reiwa, a commencé le 1er mai 2019, lorsque l'empereur Naruhito est monté sur le trône. Les années sont numérotées à partir du début de chaque ère.

const date = new Date('2025-03-15');

const japaneseFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'japanese',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(japaneseFormatter.format(date));
// Output: "March 15, 7 Reiwa"

L'année apparaît comme 7 Reiwa, indiquant la septième année de l'ère Reiwa. Ce format est utilisé dans les documents officiels japonais, les formulaires gouvernementaux et les contextes formels.

Le formatage en langue japonaise produit le format de date traditionnel japonais.

const date = new Date('2025-03-15');

const japaneseFormatter = new Intl.DateTimeFormat('ja-JP', {
  calendar: 'japanese',
  era: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(japaneseFormatter.format(date));
// Output: "令和7年3月15日"

Le résultat affiche le nom de l'ère (令和), l'année (7年), le mois (3月) et le jour (15日) en utilisant des caractères japonais.

Formatage des dates avec le calendrier chinois

Le calendrier chinois est un calendrier luni-solaire utilisé pour déterminer les fêtes traditionnelles chinoises comme le Nouvel An chinois et la Fête de la mi-automne. Ce calendrier combine les mois lunaires avec les termes solaires.

const date = new Date('2025-03-15');

const chineseFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'chinese',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(chineseFormatter.format(date));
// Output: "Second Month 16, 2025(yi-si)"

L'année du calendrier chinois inclut un nom cyclique (yi-si dans ce cas) ainsi que l'année numérique. Les noms des mois utilisent des désignations numériques comme "Premier Mois" et "Deuxième Mois".

Le formatage en langue chinoise affiche la date en utilisant des caractères chinois.

const date = new Date('2025-03-15');

const chineseFormatter = new Intl.DateTimeFormat('zh-CN', {
  calendar: 'chinese',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(chineseFormatter.format(date));
// Output: "2025乙巳年二月十六"

Formatage des dates avec le calendrier persan

Le calendrier persan, également appelé calendrier solaire hijri, est le calendrier officiel de l'Iran et de l'Afghanistan. Il utilise une année solaire avec 12 mois, similaire dans sa structure au calendrier grégorien mais avec des longueurs de mois différentes et une époque différente.

const date = new Date('2025-03-15');

const persianFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'persian',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(persianFormatter.format(date));
// Output: "Esfand 24, 1403 AP"

L'année persane 1403 correspond à l'année grégorienne 2025. L'abréviation AP signifie Anno Persico.

Le formatage en langue persane utilise des chiffres et des noms de mois persans.

const date = new Date('2025-03-15');

const persianFormatter = new Intl.DateTimeFormat('fa-IR', {
  calendar: 'persian',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(persianFormatter.format(date));
// Output: "۲۴ اسفند ۱۴۰۳ ه‍.ش."

Autres systèmes de calendrier pris en charge

JavaScript prend en charge des systèmes de calendrier supplémentaires pour divers contextes culturels et religieux.

Le calendrier buddhist ajoute 543 ans à l'année grégorienne, utilisé en Thaïlande et dans d'autres pays bouddhistes theravada.

const date = new Date('2025-03-15');

const buddhistFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'buddhist',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(buddhistFormatter.format(date));
// Output: "March 15, 2568 BE"

Le calendrier indian est le calendrier civil officiel de l'Inde.

const date = new Date('2025-03-15');

const indianFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'indian',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(indianFormatter.format(date));
// Output: "Phalguna 24, 1946 Saka"

Le calendrier coptic est utilisé par l'Église orthodoxe copte. Le calendrier ethiopic est utilisé en Éthiopie.

const date = new Date('2025-03-15');

const copticFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'coptic',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

const ethiopicFormatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'ethiopic',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(copticFormatter.format(date));
// Output: "Amshir 6, 1741 ERA1"

console.log(ethiopicFormatter.format(date));
// Output: "Yekatit 6, 2017 ERA1"

Découvrir les calendriers pris en charge

La méthode Intl.supportedValuesOf() renvoie un tableau de tous les identifiants de calendrier pris en charge par l'implémentation JavaScript.

const calendars = Intl.supportedValuesOf('calendar');
console.log(calendars);
// Résultat : ["buddhist", "chinese", "coptic", "dangi", "ethioaa", "ethiopic",
//          "gregory", "hebrew", "indian", "islamic", "islamic-civil",
//          "islamic-tbla", "islamic-umalqura", "japanese", "persian", "roc"]

La liste exacte varie selon le moteur JavaScript et la version du navigateur. La méthode renvoie toujours les calendriers par ordre alphabétique.

Vous pouvez vérifier si un calendrier spécifique est pris en charge avant de l'utiliser.

const calendars = Intl.supportedValuesOf('calendar');
const supportsIslamic = calendars.includes('islamic');

if (supportsIslamic) {
  const formatter = new Intl.DateTimeFormat('en-US', {
    calendar: 'islamic',
    dateStyle: 'long'
  });
  console.log(formatter.format(new Date()));
}

Cette vérification évite les erreurs dans les environnements qui pourraient ne pas prendre en charge tous les systèmes de calendrier.

Spécifier le calendrier avec l'extension Unicode

Vous pouvez spécifier le système de calendrier en utilisant une clé d'extension Unicode dans l'identifiant de locale au lieu d'utiliser le paramètre options. Ajoutez -u-ca- suivi de l'identifiant du calendrier à la chaîne de locale.

const date = new Date('2025-03-15');

const formatter = new Intl.DateTimeFormat('en-US-u-ca-islamic', {
  dateStyle: 'long'
});

console.log(formatter.format(date));
// Résultat : "Ramadan 16, 1447 AH"

L'extension -u-ca-islamic indique au formateur d'utiliser le calendrier islamique. Cela produit le même résultat que de passer calendar: 'islamic' dans l'objet options.

Lorsque vous spécifiez le calendrier à la fois dans la chaîne de locale et dans l'objet options, l'objet options a la priorité.

const date = new Date('2025-03-15');

const formatter = new Intl.DateTimeFormat('en-US-u-ca-islamic', {
  calendar: 'hebrew',
  dateStyle: 'long'
});

console.log(formatter.format(date));
// Résultat : "14 Adar II 5785"

Le calendrier hébreu de l'objet options remplace le calendrier islamique de la chaîne de locale. Utilisez le paramètre options lorsque vous devez contrôler programmatiquement le système de calendrier. Utilisez l'extension Unicode lorsque vous travaillez avec des identifiants de locale provenant des préférences utilisateur ou de la configuration.

Comment les locales déterminent les calendriers par défaut

Lorsque vous ne spécifiez pas de calendrier, le formateur utilise le calendrier par défaut pour la locale. La plupart des locales utilisent par défaut le calendrier grégorien, mais certaines locales utilisent des valeurs par défaut différentes.

const date = new Date('2025-03-15');

const usFormatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'long'
});

const saFormatter = new Intl.DateTimeFormat('ar-SA', {
  dateStyle: 'long'
});

const ilFormatter = new Intl.DateTimeFormat('he-IL', {
  dateStyle: 'long'
});

console.log(usFormatter.format(date));
// Output: "March 15, 2025"

console.log(saFormatter.format(date));
// Output: "١٦ رمضان ١٤٤٧ هـ"

console.log(ilFormatter.format(date));
// Output: "15 במרץ 2025"

La locale anglaise américaine utilise le calendrier grégorien par défaut. La locale arabe d'Arabie Saoudite utilise le calendrier islamique par défaut. La locale hébraïque israélienne utilise le calendrier grégorien par défaut malgré de fortes traditions liées au calendrier hébraïque.

Vous pouvez découvrir quel calendrier un formateur utilise en appelant la méthode resolvedOptions().

const formatter = new Intl.DateTimeFormat('ar-SA', {
  dateStyle: 'long'
});

const options = formatter.resolvedOptions();
console.log(options.calendar);
// Output: "islamic-umalqura"

Les options résolues montrent que la locale ar-SA utilise par défaut la variante de calendrier islamic-umalqura.

Quand définir explicitement le calendrier

Laissez la locale déterminer le système de calendrier lors du formatage des dates pour l'affichage général aux utilisateurs dans leur locale native. Les utilisateurs d'Arabie Saoudite s'attendent à des dates du calendrier islamique. Les utilisateurs du Japon s'attendent à un formatage selon l'ère japonaise dans les contextes officiels. Les paramètres par défaut de la locale gèrent automatiquement ces attentes.

const date = new Date('2025-03-15');

const formatter = new Intl.DateTimeFormat(navigator.language, {
  dateStyle: 'long'
});

console.log(formatter.format(date));
// La sortie varie selon la locale de l'utilisateur et le calendrier par défaut

Définissez explicitement le calendrier lorsque vous devez afficher des dates dans un système de calendrier spécifique, quelle que soit la locale de l'utilisateur. Une application d'heures de prière devrait toujours afficher les dates du calendrier islamique. Une application de calendrier hébraïque devrait toujours afficher les dates hébraïques.

const date = new Date('2025-03-15');

const formatter = new Intl.DateTimeFormat(navigator.language, {
  calendar: 'islamic',
  dateStyle: 'long'
});

console.log(formatter.format(date));
// La sortie affiche la date du calendrier islamique dans la langue de l'utilisateur

Cela garantit que le système de calendrier correspond à l'objectif de votre application tout en respectant les préférences linguistiques de l'utilisateur.

Définissez explicitement le calendrier lors de l'affichage des dates dans un système de calendrier différent de celui par défaut de la locale. Vous pourriez vouloir afficher des dates grégoriennes pour les utilisateurs hébreux ou des dates islamiques pour les anglophones.

const date = new Date('2025-03-15');

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'hebrew',
  dateStyle: 'long'
});

console.log(formatter.format(date));
// Output: "14 Adar II 5785"

Combiner le calendrier avec d'autres options

L'option de calendrier fonctionne avec toutes les autres options Intl.DateTimeFormat. Vous pouvez la combiner avec dateStyle, timeStyle, des options de composants comme weekday et month, et d'autres options comme timeZone.

const date = new Date('2025-03-15T14:30:00');

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic',
  dateStyle: 'full',
  timeStyle: 'long',
  timeZone: 'America/New_York'
});

console.log(formatter.format(date));
// Output: "Saturday, Ramadan 16, 1447 AH at 2:30:00 PM EST"

Le formateur utilise le calendrier islamique pour la date tout en appliquant le style de date complet, le style d'heure long et le fuseau horaire spécifié.

Vous pouvez également utiliser l'option de calendrier avec des options de composants individuels.

const date = new Date('2025-03-15');

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'japanese',
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  era: 'long'
});

console.log(formatter.format(date));
// Output: "Saturday, March 15, 7 Reiwa"

L'option d'ère devient particulièrement pertinente lors de l'utilisation de calendriers comme le japonais ou le bouddhiste qui utilisent des noms d'ère.

Formatage des plages de dates avec différents calendriers

La méthode formatRange() fonctionne avec l'option de calendrier pour formater des plages de dates dans n'importe quel système de calendrier.

const startDate = new Date('2025-03-15');
const endDate = new Date('2025-03-25');

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
});

console.log(formatter.formatRange(startDate, endDate));
// Output: "Ramadan 16 – 26, 1447 AH"

Le formateur applique le calendrier islamique aux deux dates et les formate comme une plage, en omettant intelligemment les informations répétées.

Réutilisation des formateurs pour la performance

La création d'instances Intl.DateTimeFormat implique le traitement des données de locale et des informations du système de calendrier. Lors du formatage de plusieurs dates avec le même calendrier et la même locale, créez le formateur une seule fois et réutilisez-le.

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic',
  dateStyle: 'long'
});

const dates = [
  new Date('2025-03-15'),
  new Date('2025-04-20'),
  new Date('2025-06-10')
];

dates.forEach(date => {
  console.log(formatter.format(date));
});
// Output:
// "Ramadan 16, 1447 AH"
// "Dhuʻl-Qiʻdah 22, 1447 AH"
// "Dhuʻl-Hijjah 15, 1447 AH"

Cette approche améliore les performances lors du formatage de tableaux de dates ou de l'affichage de nombreux horodatages dans votre application.

Ce qu'il faut retenir

Les systèmes de calendrier définissent comment les cultures organisent et comptent le temps. JavaScript prend en charge plus de 17 systèmes de calendrier différents, notamment les calendriers islamique, hébreu, japonais, chinois, persan, bouddhiste et copte, grâce à l'API Intl.DateTimeFormat.

Spécifiez un système de calendrier en utilisant l'option calendar dans l'objet d'options ou en ajoutant une extension Unicode à la chaîne de paramètres régionaux. L'option de calendrier détermine quel système de calendrier formate la date, tandis que les paramètres régionaux déterminent la langue et les conventions de formatage.

Laissez les paramètres régionaux déterminer le calendrier par défaut lors de l'affichage des dates pour un usage général. Définissez explicitement le calendrier lorsque votre application nécessite un système de calendrier spécifique, indépendamment des préférences de paramètres régionaux de l'utilisateur.

L'option de calendrier fonctionne avec toutes les autres options de formatage de date, y compris les styles, les options de composants, les fuseaux horaires et les plages de dates. Réutilisez les instances de formateur lors du formatage de plusieurs dates pour de meilleures performances.