API Intl.Locale - JavaScript i18n

Introduction

Lors de la création d'applications pour plusieurs langues et régions, vous rencontrez des identifiants de locale comme en-US, fr-FR, ou zh-Hans-CN. Ces chaînes apparaissent dans les API du navigateur, les en-têtes HTTP et les préférences utilisateur. Elles encodent des informations sur la langue, la région, le système d'écriture et les préférences de formatage.

L'API Intl.Locale transforme ces chaînes opaques en objets structurés que vous pouvez inspecter et manipuler. Au lieu d'analyser manuellement les chaînes ou de deviner ce que signifie zh-Hans-CN, vous créez un objet locale et lisez directement ses propriétés.

Ce guide explique comment fonctionnent les identifiants de locale, comment utiliser l'API Intl.Locale pour travailler avec eux, et quand les objets de locale structurés aident à résoudre des problèmes réels.

Comprendre les identifiants de locale

Un identifiant de locale est une chaîne qui spécifie les préférences culturelles pour le formatage des dates, des nombres, des devises et du texte. L'identifiant contient plusieurs composants séparés par des traits d'union.

La structure la plus courante suit la norme BCP 47 :

langue-écriture-région-variante-extensions

Chaque composant est optionnel à l'exception du code de langue.

Codes de langue

Les codes de langue utilisent deux ou trois lettres de la norme ISO 639. Exemples courants :

en pour l'anglais
es pour l'espagnol
fr pour le français
de pour l'allemand
ja pour le japonais
zh pour le chinois
ar pour l'arabe

Le code de langue est toujours en minuscules et apparaît en premier dans l'identifiant.

Codes de région

Les codes de région spécifient des zones géographiques en utilisant deux lettres majuscules de la norme ISO 3166-1. Ils indiquent quelle variante d'une langue utiliser :

en-US pour l'anglais américain
en-GB pour l'anglais britannique
es-ES pour l'espagnol européen
es-MX pour l'espagnol mexicain
fr-FR pour le français parlé en France
fr-CA pour le français canadien

Les codes de région modifient les conventions de formatage. L'anglais américain utilise le format de date MM/JJ/AAAA, tandis que l'anglais britannique utilise JJ/MM/AAAA.

Codes de script

Les codes de script spécifient le système d'écriture en utilisant quatre lettres avec la première lettre en majuscule. Ils sont importants pour les langues écrites dans plusieurs scripts :

zh-Hans pour les caractères chinois simplifiés
zh-Hant pour les caractères chinois traditionnels
sr-Cyrl pour le serbe en script cyrillique
sr-Latn pour le serbe en script latin

La plupart des locales omettent le code de script car la langue implique un script par défaut. L'anglais utilise le script latin par défaut, donc on écrit en au lieu de en-Latn.

Balises d'extension

Les balises d'extension ajoutent des préférences de formatage aux identificateurs de locale. Elles commencent par -u- suivi de paires clé-valeur :

en-US-u-ca-gregory-nu-latn-hc-h12

Clés d'extension courantes :

ca pour le système de calendrier (gregory, buddhist, islamic)
nu pour le système de numération (latn, arab, hanidec)
hc pour le cycle horaire (h12, h23, h11, h24)

Les extensions personnalisent l'affichage des données par les formateurs sans changer la langue ou la région.

Création d'objets locale

Le constructeur Intl.Locale accepte une chaîne d'identificateur de locale et renvoie un objet structuré :

const locale = new Intl.Locale("en-US");

console.log(locale.language); // "en"
console.log(locale.region); // "US"

Vous pouvez également passer un objet d'options pour remplacer ou ajouter des propriétés :

const locale = new Intl.Locale("en", {
  region: "GB",
  hourCycle: "h23"
});

console.log(locale.baseName); // "en-GB"
console.log(locale.hourCycle); // "h23"

Le constructeur lance une RangeError si l'identificateur est invalide :

try {
  const invalid = new Intl.Locale("invalid-locale-code");
} catch (error) {
  console.error(error.message); // "invalid language subtag: invalid"
}

Cette validation garantit que vous détectez les identificateurs de locale mal formés avant de les transmettre aux formateurs.

Lecture des propriétés de locale

Les objets Locale exposent des propriétés qui correspondent aux composants de la chaîne d'identificateur. Toutes les propriétés sont en lecture seule.

Propriétés fondamentales

La propriété language renvoie le code de langue :

const locale = new Intl.Locale("fr-CA");
console.log(locale.language); // "fr"

La propriété region renvoie le code de région :

const locale = new Intl.Locale("fr-CA");
console.log(locale.region); // "CA"

La propriété script renvoie le code de script s'il est présent :

const locale = new Intl.Locale("zh-Hans-CN");
console.log(locale.script); // "Hans"

La propriété baseName renvoie l'identifiant fondamental complet sans extensions :

const locale = new Intl.Locale("en-US-u-ca-gregory-nu-latn");
console.log(locale.baseName); // "en-US"

Utilisez baseName lorsque vous avez besoin de la langue et de la région mais souhaitez ignorer les préférences de formatage.

Propriétés d'extension

Les propriétés d'extension renvoient des valeurs de la balise d'extension -u- ou undefined si non spécifiées.

La propriété calendar renvoie le système de calendrier :

const locale = new Intl.Locale("ar-SA-u-ca-islamic");
console.log(locale.calendar); // "islamic"

La propriété numberingSystem renvoie le système de numération :

const locale = new Intl.Locale("ar-EG-u-nu-arab");
console.log(locale.numberingSystem); // "arab"

La propriété hourCycle renvoie la préférence de cycle horaire :

const locale = new Intl.Locale("en-US-u-hc-h23");
console.log(locale.hourCycle); // "h23"

La propriété caseFirst renvoie la préférence de casse pour le tri :

const locale = new Intl.Locale("en-US-u-kf-upper");
console.log(locale.caseFirst); // "upper"

La propriété numeric indique si le tri numérique est activé :

const locale = new Intl.Locale("en-US-u-kn-true");
console.log(locale.numeric); // true

Ces propriétés vous permettent d'examiner les préférences de formatage sans avoir à analyser manuellement la chaîne d'extension.

Interrogation des informations de locale

L'API Intl.Locale fournit des méthodes qui renvoient des tableaux d'options disponibles pour une locale. Ces méthodes aident à construire des interfaces utilisateur et à valider les choix de formatage.

Calendriers disponibles

La méthode getCalendars() renvoie les systèmes de calendrier couramment utilisés pour la locale :

const locale = new Intl.Locale("th-TH");
const calendars = locale.getCalendars();
console.log(calendars); // ["buddhist", "gregory"]

Le premier élément est le calendrier par défaut. Les locales thaïlandaises utilisent par défaut le calendrier bouddhiste mais utilisent également le calendrier grégorien.

Collations disponibles

La méthode getCollations() renvoie les types de collation pour le tri des chaînes :

const locale = new Intl.Locale("de-DE");
const collations = locale.getCollations();
console.log(collations); // ["phonebk", "emoji", "eor"]

L'allemand possède une collation de type annuaire téléphonique qui trie les chaînes différemment de la collation Unicode standard.

Cycles horaires disponibles

La méthode getHourCycles() renvoie les formats de cycle horaire :

const locale = new Intl.Locale("en-US");
const hourCycles = locale.getHourCycles();
console.log(hourCycles); // ["h12"]

L'anglais américain utilise le format 12 heures par défaut. De nombreuses autres locales renvoient ["h23"] pour le format 24 heures.

Systèmes de numération disponibles

La méthode getNumberingSystems() renvoie les systèmes de numération couramment utilisés pour la locale :

const locale = new Intl.Locale("ar-EG");
const numberingSystems = locale.getNumberingSystems();
console.log(numberingSystems); // ["arab", "latn"]

Les locales arabes prennent souvent en charge à la fois les chiffres arabo-indiens et les chiffres latins.

Direction du texte

La méthode getTextInfo() renvoie des informations sur l'ordre du texte :

const locale = new Intl.Locale("ar-SA");
const textInfo = locale.getTextInfo();
console.log(textInfo.direction); // "rtl"

Les langues de droite à gauche comme l'arabe et l'hébreu renvoient "rtl". Les langues de gauche à droite renvoient "ltr".

Conventions de semaine

La méthode getWeekInfo() renvoie la structure de la semaine pour la locale :

const locale = new Intl.Locale("en-US");
const weekInfo = locale.getWeekInfo();
console.log(weekInfo.firstDay); // 7 (dimanche)
console.log(weekInfo.weekend); // [6, 7] (samedi, dimanche)
console.log(weekInfo.minimalDays); // 1

Les conventions de semaine varient selon les régions. Les semaines américaines commencent le dimanche, tandis que la plupart des semaines européennes commencent le lundi.

Fuseaux horaires

La méthode getTimeZones() renvoie les fuseaux horaires pour la région de la locale :

const locale = new Intl.Locale("en-US");
const timeZones = locale.getTimeZones();
console.log(timeZones); // ["America/New_York", "America/Chicago", ...]

Cette méthode renvoie les identifiants de fuseau horaire IANA pour le code de région.

Maximisation des identifiants de locale

La méthode maximize() ajoute les sous-balises probables pour créer un identifiant complet. Elle déduit les codes de script et de région manquants en se basant sur les données linguistiques.

Lorsque vous spécifiez uniquement un code de langue, maximize() ajoute le script et la région les plus courants :

const locale = new Intl.Locale("en");
const maximized = locale.maximize();
console.log(maximized.baseName); // "en-Latn-US"

L'anglais utilise par défaut le script latin et la région États-Unis car ce sont les associations les plus courantes.

La maximisation du chinois dépend du script :

const simplified = new Intl.Locale("zh-Hans");
const maximized = simplified.maximize();
console.log(maximized.baseName); // "zh-Hans-CN"

const traditional = new Intl.Locale("zh-Hant");
const maximizedTrad = traditional.maximize();
console.log(maximizedTrad.baseName); // "zh-Hant-TW"

Le chinois simplifié est associé à la Chine, tandis que le chinois traditionnel est associé à Taïwan.

Utilisez maximize() lors de la normalisation des entrées utilisateur ou de la comparaison des identifiants de locale. Cela rend explicites les informations implicites.

Minimisation des identifiants de locale

La méthode minimize() supprime les sous-balises redondantes pour créer l'identifiant équivalent le plus court. Elle supprime les codes de script et de région lorsqu'ils correspondent aux valeurs par défaut probables.

Lorsqu'une locale utilise le script et la région par défaut, minimize() les supprime :

const locale = new Intl.Locale("en-Latn-US");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en"

Le script latin et la région États-Unis étant les valeurs par défaut pour l'anglais, ils peuvent être supprimés sans perdre d'information.

Pour les locales avec des régions non par défaut, minimize() conserve la région :

const locale = new Intl.Locale("en-Latn-GB");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en-GB"

L'anglais britannique nécessite le code de région car il diffère de la valeur par défaut.

Utilisez minimize() pour créer des identifiants compacts pour le stockage ou les URL tout en préservant leur signification.

Conversion en chaînes de caractères

La méthode toString() renvoie l'identifiant de locale complet, y compris les extensions :

const locale = new Intl.Locale("en-US", {
  calendar: "gregory",
  numberingSystem: "latn",
  hourCycle: "h12"
});

console.log(locale.toString()); // "en-US-u-ca-gregory-hc-h12-nu-latn"

La représentation sous forme de chaîne est valide pour être transmise à d'autres API Intl ou stockée comme données de configuration.

Vous pouvez également convertir implicitement des objets locale en chaînes :

const locale = new Intl.Locale("fr-FR");
const formatter = new Intl.DateTimeFormat(locale);

Le constructeur DateTimeFormat accepte directement les objets locale et appelle toString() en interne.

Cas d'utilisation pratiques

L'API Intl.Locale résout plusieurs problèmes courants lors de la création d'applications internationalisées.

Création de sélecteurs de locale

Les sélecteurs de locale permettent aux utilisateurs de choisir leur langue et leur région. L'API Intl.Locale aide à analyser et à valider les sélections des utilisateurs :

function createLocaleSelector(locales) {
  const options = locales.map(identifier => {
    const locale = new Intl.Locale(identifier);
    const displayName = new Intl.DisplayNames([identifier], { type: "language" });

    return {
      value: locale.toString(),
      label: displayName.of(locale.language),
      region: locale.region
    };
  });

  return options;
}

const options = createLocaleSelector(["en-US", "en-GB", "fr-FR", "es-MX"]);
console.log(options);
// [
//   { value: "en-US", label: "English", region: "US" },
//   { value: "en-GB", label: "English", region: "GB" },
//   { value: "fr-FR", label: "French", region: "FR" },
//   { value: "es-MX", label: "Spanish", region: "MX" }
// ]

Validation des entrées de locale

Lors de l'acceptation d'identifiants de locale provenant de saisies utilisateur ou de fichiers de configuration, validez-les avant utilisation :

function validateLocale(identifier) {
  try {
    const locale = new Intl.Locale(identifier);
    return {
      valid: true,
      locale: locale.toString(),
      language: locale.language,
      region: locale.region
    };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

console.log(validateLocale("en-US")); // { valid: true, locale: "en-US", ... }
console.log(validateLocale("invalid")); // { valid: false, error: "..." }

Extraction de la langue pour les solutions de repli

Lors de l'implémentation de chaînes de repli linguistique, extrayez le code de langue sans la région :

function getLanguageFallback(identifier) {
  const locale = new Intl.Locale(identifier);
  const fallbacks = [locale.toString()];

  if (locale.region) {
    const languageOnly = new Intl.Locale(locale.language);
    fallbacks.push(languageOnly.toString());
  }

  fallbacks.push("en");

  return fallbacks;
}

console.log(getLanguageFallback("fr-CA"));
// ["fr-CA", "fr", "en"]

Cela crée une chaîne de repli qui essaie d'abord la locale spécifique, puis la langue sans région, puis la langue par défaut.

Configuration des formateurs

Utilisez des objets locale pour configurer les formateurs Intl avec des préférences spécifiques :

function createFormatter(baseLocale, options = {}) {
  const locale = new Intl.Locale(baseLocale, {
    calendar: options.calendar || "gregory",
    numberingSystem: options.numberingSystem || "latn",
    hourCycle: options.hourCycle || "h23"
  });

  return {
    date: new Intl.DateTimeFormat(locale),
    number: new Intl.NumberFormat(locale),
    locale: locale.toString()
  };
}

const formatter = createFormatter("ar-SA", {
  calendar: "islamic",
  numberingSystem: "arab"
});

console.log(formatter.locale); // "ar-SA-u-ca-islamic-nu-arab"

Détection des préférences utilisateur

Les API du navigateur fournissent des chaînes de caractères de locale que vous pouvez analyser pour comprendre les préférences de l'utilisateur :

function getUserPreferences() {
  const userLocale = new Intl.Locale(navigator.language);
  const hourCycles = userLocale.getHourCycles();
  const calendars = userLocale.getCalendars();
  const textInfo = userLocale.getTextInfo();

  return {
    language: userLocale.language,
    region: userLocale.region,
    preferredHourCycle: hourCycles[0],
    preferredCalendar: calendars[0],
    textDirection: textInfo.direction
  };
}

const preferences = getUserPreferences();
console.log(preferences);
// { language: "en", region: "US", preferredHourCycle: "h12", ... }

Cela crée un profil des préférences de l'utilisateur basé sur les paramètres de son navigateur.

Compatibilité des navigateurs

L'API Intl.Locale fonctionne dans tous les navigateurs modernes. Chrome, Firefox, Safari et Edge offrent une prise en charge complète du constructeur, des propriétés et des méthodes décrites dans ce guide.

Les méthodes plus récentes comme getCalendars(), getCollations(), getHourCycles(), getNumberingSystems(), getTextInfo(), getTimeZones() et getWeekInfo() nécessitent des versions récentes de navigateurs. Vérifiez les tableaux de compatibilité des navigateurs avant d'utiliser ces méthodes si vous prenez en charge des navigateurs plus anciens.

Node.js prend en charge l'API Intl.Locale à partir de la version 12, avec une prise en charge complète des méthodes dans la version 18 et ultérieures.

Résumé

L'API Intl.Locale transforme les chaînes d'identificateurs de locale en objets structurés que vous pouvez inspecter et manipuler. Au lieu d'analyser manuellement les chaînes, vous créez des objets locale et lisez leurs propriétés.

Concepts fondamentaux :

Les identificateurs de locale contiennent des composants de langue, d'écriture, de région et d'extension
Le constructeur Intl.Locale valide les identificateurs et crée des objets
Les propriétés comme language, region et calendar fournissent un accès structuré
Les méthodes comme getCalendars() et getHourCycles() renvoient les options disponibles
Les méthodes maximize() et minimize() normalisent les identificateurs
Les objets locale fonctionnent directement avec d'autres API Intl

Utilisez l'API Intl.Locale lors de la création de sélecteurs de locale, de la validation des entrées utilisateur, de l'implémentation de chaînes de repli ou de la configuration des formateurs. Elle fournit une méthode standard pour travailler avec des identificateurs de locale dans les applications JavaScript.