Comment formater les heures selon la locale de l'utilisateur

Introduction

Les heures apparaissent différemment à travers le monde. Les Américains voient généralement 3:30 PM affiché comme 3:30 PM, tandis que la plupart des Européens s'attendent à voir 15:30. Lorsque vous codez en dur un format d'heure, vous supposez que tous les utilisateurs suivent la même convention.

Afficher des heures dans un format non familier crée de la confusion. Un utilisateur habitué au format 24 heures qui voit 3:30 PM doit faire une conversion mentale pour comprendre s'il s'agit du matin ou de l'après-midi. Cette charge cognitive s'accumule pour chaque heure dans votre application.

JavaScript fournit l'API Intl.DateTimeFormat pour gérer le formatage des heures automatiquement. Cette leçon explique pourquoi les formats d'heure varient selon les cultures, comment l'API fonctionne, et comment formater correctement les heures pour n'importe quelle locale.

Pourquoi les formats d'heure varient selon la locale

Différentes régions ont développé différentes conventions pour afficher les heures. Ces conventions reflètent des pratiques historiques, des systèmes éducatifs et des préférences culturelles. Aucun format n'est universel.

Aux États-Unis, au Canada, en Australie et aux Philippines, les heures utilisent le format 12 heures avec les indicateurs AM et PM. 3:30 de l'après-midi apparaît comme 3:30 PM.

Dans la plupart des pays européens, en Amérique latine et en Asie, les heures utilisent le format 24 heures sans indicateurs AM ou PM. La même heure apparaît comme 15:30.

Le caractère séparateur entre les heures et les minutes varie également. Les pays anglophones utilisent les deux-points, tandis que certaines locales utilisent des points ou d'autres signes de ponctuation.

La façon dont AM et PM apparaissent diffère aussi. L'anglais utilise AM et PM, l'espagnol utilise a.m. et p.m., et certaines locales placent ces indicateurs avant l'heure plutôt qu'après.

Lorsque vous affichez des heures, vous devez correspondre aux attentes de l'utilisateur tant pour le format d'heure que pour les conventions de formatage spécifiques.

Utilisation d'Intl.DateTimeFormat pour formater les heures

Le constructeur Intl.DateTimeFormat crée un formateur qui applique des conventions spécifiques à la locale. Pour formater les heures, passez un identifiant de locale comme premier argument et spécifiez les options liées à l'heure dans le second argument.

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric'
});

const date = new Date('2025-03-15T15:30:00');
console.log(formatter.format(date));
// Résultat : "3:30 PM"

Cela crée un formateur pour l'anglais américain qui affiche les heures et les minutes. Les options hour et minute indiquent au formateur d'inclure ces composants. La méthode format() convertit l'objet Date en une chaîne de caractères avec le formatage approprié.

Le constructeur Date accepte une chaîne de date et heure au format ISO 8601 comme 2025-03-15T15:30:00. Cela crée un objet Date représentant 15h30 le 15 mars 2025. Le formateur convertit ensuite cette date en une chaîne d'heure spécifique à la locale.

Formatage de la même heure pour différentes locales

Vous pouvez formater la même heure pour différentes locales en changeant l'identifiant de locale passé au constructeur.

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

const usFormatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric'
});
console.log(usFormatter.format(date));
// Résultat : "3:30 PM"

const gbFormatter = new Intl.DateTimeFormat('en-GB', {
  hour: 'numeric',
  minute: 'numeric'
});
console.log(gbFormatter.format(date));
// Résultat : "15:30"

const deFormatter = new Intl.DateTimeFormat('de-DE', {
  hour: 'numeric',
  minute: 'numeric'
});
console.log(deFormatter.format(date));
// Résultat : "15:30"

const frFormatter = new Intl.DateTimeFormat('fr-FR', {
  hour: 'numeric',
  minute: 'numeric'
});
console.log(frFormatter.format(date));
// Résultat : "15:30"

Chaque formateur applique des conventions différentes. Le formateur américain utilise le format 12 heures avec AM/PM. Les formateurs britannique, allemand et français utilisent tous le format 24 heures sans indicateurs AM/PM.

Vous n'avez pas besoin de connaître le format utilisé par chaque locale. L'API gère automatiquement ces détails en fonction de l'identifiant de locale.

Inclure les secondes dans l'affichage de l'heure

Vous pouvez ajouter l'option second pour afficher les secondes avec les heures et les minutes.

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric'
});

const date = new Date('2025-03-15T15:30:45');
console.log(formatter.format(date));
// Output: "3:30:45 PM"

L'option second fonctionne de la même manière que hour et minute. Définissez-la sur 'numeric' pour inclure les secondes dans la sortie.

Contrôler le remplissage des chiffres avec 2-digit

Les options hour, minute et second acceptent deux valeurs : 'numeric' et '2-digit'. La valeur 'numeric' affiche les chiffres sans remplissage, tandis que '2-digit' affiche toujours deux chiffres avec des zéros en tête.

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

const numericFormatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric'
});
console.log(numericFormatter.format(date));
// Output: "9:05:03 AM"

const twoDigitFormatter = new Intl.DateTimeFormat('en-US', {
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit'
});
console.log(twoDigitFormatter.format(date));
// Output: "09:05:03 AM"

Le formateur numérique affiche 9:05:03 AM avec un seul chiffre pour l'heure. Le formateur à deux chiffres affiche 09:05:03 AM avec un zéro en tête pour l'heure. Les deux affichent deux chiffres pour les minutes et les secondes car ces valeurs sont généralement complétées indépendamment du paramètre.

Forcer le format 12 heures ou 24 heures

Par défaut, l'API utilise le format d'heure préféré par la locale. Vous pouvez remplacer cela avec l'option hour12.

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

const hour12Formatter = new Intl.DateTimeFormat('en-GB', {
  hour: 'numeric',
  minute: 'numeric',
  hour12: true
});
console.log(hour12Formatter.format(date));
// Output: "3:30 pm"

const hour24Formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric',
  hour12: false
});
console.log(hour24Formatter.format(date));
// Output: "15:30"

Définir hour12: true force le format 12 heures même pour les locales qui utilisent normalement le format 24 heures. Définir hour12: false force le format 24 heures même pour les locales qui utilisent normalement le format 12 heures.

La locale détermine toujours d'autres détails de formatage comme la ponctuation et l'espacement. Le formateur britannique avec hour12: true affiche 3:30 pm avec pm en minuscules, tandis qu'un formateur américain afficherait 3:30 PM avec PM en majuscules.

Formatage des heures selon les paramètres régionaux de l'utilisateur

Au lieu de coder en dur une locale spécifique, vous pouvez utiliser la langue préférée de l'utilisateur depuis le navigateur. La propriété navigator.language renvoie la préférence linguistique principale de l'utilisateur.

const userLocale = navigator.language;
const formatter = new Intl.DateTimeFormat(userLocale, {
  hour: 'numeric',
  minute: 'numeric'
});

const date = new Date('2025-03-15T15:30:00');
console.log(formatter.format(date));
// Le résultat varie selon la locale de l'utilisateur
// Pour en-US : "3:30 PM"
// Pour en-GB : "15:30"
// Pour de-DE : "15:30"
// Pour fr-FR : "15:30"

Cette approche affiche les heures selon les attentes de chaque utilisateur sans leur demander de sélectionner manuellement une locale. Le navigateur fournit la préférence linguistique, et l'API Intl applique les conventions de formatage appropriées.

Vous pouvez également passer le tableau complet des langues préférées pour activer le comportement de repli.

const formatter = new Intl.DateTimeFormat(navigator.languages, {
  hour: 'numeric',
  minute: 'numeric'
});

const date = new Date('2025-03-15T15:30:00');
console.log(formatter.format(date));

L'API utilise la première locale qu'elle prend en charge dans le tableau. Cela offre une meilleure gestion du repli lorsque la préférence principale de l'utilisateur n'est pas disponible.

Création d'heures à formater

Vous pouvez créer des objets Date avec des informations temporelles de plusieurs façons. L'approche la plus fiable consiste à utiliser des chaînes de date et heure au format ISO 8601.

const time1 = new Date('2025-03-15T09:00:00');
const time2 = new Date('2025-03-15T15:30:00');
const time3 = new Date('2025-03-15T23:45:30');

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric'
});

console.log(formatter.format(time1));
// Résultat : "9:00 AM"

console.log(formatter.format(time2));
// Résultat : "3:30 PM"

console.log(formatter.format(time3));
// Résultat : "11:45 PM"

Les chaînes de date et heure ISO 8601 utilisent le format YYYY-MM-DDTHH:MM:SS. Le T sépare la date de l'heure. Ce format est sans ambiguïté et fonctionne de manière cohérente dans toutes les locales et fuseaux horaires.

Formatage des heures à partir de timestamps

Vous pouvez également créer des objets Date à partir de timestamps Unix. Un timestamp Unix représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC.

const timestamp = 1710515400000; // 15 mars 2025 à 15h30
const date = new Date(timestamp);

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric'
});
console.log(formatter.format(date));
// Résultat : "3:30 PM"

Cette approche fonctionne lorsque vous recevez des timestamps d'APIs, de bases de données ou d'autres systèmes qui représentent les heures sous forme de nombres.

Vous pouvez également passer le timestamp directement à la méthode format() sans créer d'abord un objet Date.

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric'
});

const timestamp = 1710515400000;
console.log(formatter.format(timestamp));
// Résultat : "3:30 PM"

L'API accepte à la fois les objets Date et les timestamps. Utilisez l'approche qui convient le mieux à votre code.

Formatage de l'heure actuelle

Pour formater l'heure actuelle, créez un objet Date sans arguments. Cela crée un objet Date représentant le moment présent.

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric'
});

const now = new Date();
console.log(formatter.format(now));
// Résultat : "3:45:12 PM" (ou l'heure actuelle lors de l'exécution)

Vous pouvez également passer directement Date.now(), qui renvoie le timestamp actuel sous forme de nombre.

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric'
});

console.log(formatter.format(Date.now()));
// Résultat : "3:45:12 PM" (ou l'heure actuelle lors de l'exécution)

Les deux approches produisent des résultats identiques.

Réutilisation des formateurs pour les performances

La création d'une nouvelle instance Intl.DateTimeFormat implique le chargement des données de locale et le traitement des options. Lorsque vous devez formater plusieurs heures avec les mêmes paramètres de locale et de configuration, créez le formateur une seule fois et réutilisez-le.

const formatter = new Intl.DateTimeFormat('en-US', {
  hour: 'numeric',
  minute: 'numeric'
});

const times = [
  new Date('2025-03-15T09:00:00'),
  new Date('2025-03-15T12:30:00'),
  new Date('2025-03-15T18:45:00')
];

times.forEach(time => {
  console.log(formatter.format(time));
});
// Résultat :
// "9:00 AM"
// "12:30 PM"
// "6:45 PM"

Cette approche est plus efficace que de créer un nouveau formateur pour chaque heure. La différence de performance devient significative lors du formatage de tableaux contenant des centaines ou des milliers de valeurs temporelles.

Formatage des heures dans les templates

Vous pouvez utiliser Intl.DateTimeFormat partout où vous affichez des heures aux utilisateurs. Cela inclut l'insertion d'heures formatées dans des templates HTML, l'affichage d'heures dans des tableaux ou la présentation d'horodatages dans les interfaces utilisateur.

const formatter = new Intl.DateTimeFormat(navigator.language, {
  hour: 'numeric',
  minute: 'numeric'
});

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

document.getElementById('start-time').textContent = formatter.format(eventStart);
document.getElementById('end-time').textContent = formatter.format(eventEnd);

Les chaînes formatées fonctionnent comme n'importe quelle autre valeur de chaîne. Vous pouvez les insérer dans du contenu textuel, des attributs ou tout autre contexte où vous affichez des informations aux utilisateurs.