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 tels que en-US, fr-FR ou zh-Hans-CN. Ces chaînes apparaissent dans les API de 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 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, nombres, devises et texte. L'identifiant contient plusieurs composants séparés par des traits d'union.

La structure la plus courante suit la norme BCP 47 :

language-script-region-variant-extensions

Chaque composant est optionnel sauf le 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 les dates au format MM/DD/YYYY, tandis que l'anglais britannique utilise le format DD/MM/YYYY.

Codes d'écriture

Les codes d'écriture 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 systèmes d'écriture :

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

La plupart des locales omettent le code d'écriture car la langue implique un système d'écriture par défaut. L'anglais utilise l'écriture latine par défaut, donc vous écrivez en au lieu de en-Latn.

Balises d'extension

Les balises d'extension ajoutent des préférences de formatage aux identifiants 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 la façon dont les formateurs affichent les données sans modifier la langue ou la région.

Création d'objets locale

Le constructeur Intl.Locale accepte une chaîne d'identifiant 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 lève une RangeError si l'identifiant 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 identifiants 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'identifiant. Toutes les propriétés sont en lecture seule.

Propriétés principales

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 d'écriture 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 principal complet sans les 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é.

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 la collation :

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

La propriété numeric indique si la collation numérique est activée :

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

Ces propriétés vous permettent d'inspecter les préférences de formatage sans 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 facilitent la création d'interfaces utilisateur et la validation des 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 dispose d'une collation d'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 par défaut le format 12 heures. 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 les informations d'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 (Sunday)
console.log(weekInfo.weekend); // [6, 7] (Saturday, Sunday)
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 des sous-balises probables pour créer un identifiant complet. Elle déduit les codes de script et de région manquants en fonction des 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 l'écriture latine et la région des États-Unis car ce sont les associations les plus courantes.

La maximisation du chinois dépend de l'écriture :

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 d'identifiants de locale. Elle 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 l'écriture 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"

L'écriture latine et la région des États-Unis sont les valeurs par défaut pour l'anglais, elles peuvent donc être supprimées sans perte 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 le sens.

Conversion en chaînes de caractères

La méthode toString() retourne l'identifiant de locale complet incluant 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ée de configuration.

Vous pouvez également convertir les objets locale en chaînes de caractères de manière implicite :

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'usage 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 d'entrées 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 linguistiques, 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 les 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 paramètres régionaux que vous pouvez analyser pour comprendre les préférences 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 utilisateur basé sur les paramètres de leur 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 navigateur. Consultez 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'identifiants de paramètres régionaux en objets structurés que vous pouvez inspecter et manipuler. Au lieu d'analyser les chaînes manuellement, vous créez des objets de paramètres régionaux et lisez leurs propriétés.

Concepts fondamentaux :

Les identifiants de paramètres régionaux contiennent des composants de langue, d'écriture, de région et d'extension
Le constructeur Intl.Locale valide les identifiants 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 identifiants
Les objets de paramètres régionaux fonctionnent directement avec d'autres API Intl

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