Comment vérifier si un identifiant de locale est valide

Validez les identifiants de locale avant de les utiliser pour formater les dates, les nombres et les devises

Introduction

Lorsque votre application accepte des identifiants de locale à partir d'entrées utilisateur, de réponses d'API ou de fichiers de configuration, vous devez vérifier qu'ils sont valides avant de les utiliser. Un identifiant de locale invalide provoquera des erreurs dans les fonctions de formatage ou produira des résultats inattendus.

La validation garantit que des chaînes comme en-US sont structurellement correctes selon les normes internationales. Cela évite les erreurs d'exécution lors de la transmission d'identifiants de locale à l'API Intl ou à d'autres bibliothèques d'internationalisation.

JavaScript fournit deux méthodes intégrées pour valider les identifiants de locale. Les deux méthodes vérifient la structure de l'identifiant par rapport à la norme BCP 47, qui définit le format des balises de langue.

Ce qui rend un identifiant de locale valide

Un identifiant de locale suit la norme BCP 47 pour les balises de langue. Cette norme définit la structure et les règles pour combiner les composants de langue, de script, de région et d'extension.

Les identifiants de locale valides utilisent des traits d'union pour séparer les composants, et non des tirets bas ou d'autres caractères. Le code de langue doit être un code ISO 639 reconnu, et les codes de région doivent être des codes ISO 3166-1 reconnus.

Exemples d'identifiants de locale valides :

  • en (anglais)
  • en-US (anglais américain)
  • zh-Hans (chinois simplifié)
  • zh-Hans-CN (chinois simplifié utilisé en Chine)
  • en-US-u-ca-gregory (anglais américain avec calendrier grégorien)

Exemples d'identifiants de locale invalides :

  • en_US (utilise un tiret bas au lieu d'un trait d'union)
  • english (pas un code de langue reconnu)
  • en-USA (le code de région doit comporter deux lettres, pas trois)
  • EN-us (le code de langue doit être en minuscules)
  • abc-XY (le code de langue n'existe pas)

Les méthodes de validation vérifient ces règles structurelles et confirment que les codes sont des normes reconnues.

Utilisation de Intl.getCanonicalLocales pour valider

La méthode Intl.getCanonicalLocales() valide les identifiants de locale et les renvoie sous leur forme canonique. Cette méthode accepte un seul identifiant de locale ou un tableau d'identifiants.

const result = Intl.getCanonicalLocales("en-US");
console.log(result);
// Sortie : ["en-US"]

La méthode normalise l'entrée en la convertissant au format standard. Même si vous passez un identifiant de locale avec une casse incorrecte, elle renvoie la forme canonique correcte :

const result = Intl.getCanonicalLocales("EN-us");
console.log(result);
// Sortie : ["en-US"]

Lorsque vous passez un identifiant de locale invalide, la méthode génère une erreur RangeError :

try {
  Intl.getCanonicalLocales("en_US");
} catch (error) {
  console.error(error.name);
  // Sortie : "RangeError"
  console.error(error.message);
  // Sortie : "en_US is not a structurally valid language tag"
}

Cette erreur indique que l'identifiant ne suit pas la structure BCP 47. Vous pouvez capturer cette erreur pour gérer les entrées invalides de manière élégante.

Validation de plusieurs identifiants de locale

La méthode Intl.getCanonicalLocales() accepte un tableau pour valider plusieurs identifiants de locale à la fois. La méthode renvoie un tableau des formes canoniques pour tous les identifiants valides.

const locales = ["en-US", "fr-FR", "es-MX"];
const result = Intl.getCanonicalLocales(locales);
console.log(result);
// Sortie : ["en-US", "fr-FR", "es-MX"]

La méthode supprime également les identifiants de locale en double du résultat :

const locales = ["en-US", "EN-us", "en-US"];
const result = Intl.getCanonicalLocales(locales);
console.log(result);
// Sortie : ["en-US"]

Les trois valeurs d'entrée représentent la même locale, donc la méthode ne renvoie qu'une seule forme canonique.

Si une locale dans le tableau est invalide, la méthode génère une erreur :

try {
  Intl.getCanonicalLocales(["en-US", "invalid", "fr-FR"]);
} catch (error) {
  console.error(error.message);
  // Sortie : "invalid is not a structurally valid language tag"
}

Lors de la validation de listes fournies par l'utilisateur, validez chaque locale individuellement pour identifier quels identifiants spécifiques sont invalides.

Utilisation du constructeur Intl.Locale pour valider

Le constructeur Intl.Locale fournit une autre méthode pour valider les identifiants de locale. Lorsque vous créez un objet locale avec un identifiant invalide, le constructeur lance une erreur RangeError.

try {
  const locale = new Intl.Locale("en-US");
  console.log("Locale valide");
} catch (error) {
  console.error("Locale invalide");
}
// Résultat : "Locale valide"

Le constructeur lance une erreur pour les identifiants invalides :

try {
  const locale = new Intl.Locale("en_US");
  console.log("Locale valide");
} catch (error) {
  console.error("Locale invalide");
  console.error(error.message);
}
// Résultat : "Locale invalide"
// Résultat : "invalid language subtag: en_US"

Contrairement à Intl.getCanonicalLocales(), le constructeur Intl.Locale ne normalise pas la casse. Il exige que l'identifiant utilise la casse correcte :

const locale1 = new Intl.Locale("en-US");
console.log(locale1.baseName);
// Résultat : "en-US"

const locale2 = new Intl.Locale("EN-US");
console.log(locale2.baseName);
// Résultat : "en-US"

Les codes de langue en majuscules et en minuscules sont acceptés, et le constructeur les normalise vers leur forme canonique.

Choisir une méthode de validation

Les deux méthodes de validation servent des objectifs différents et offrent des fonctionnalités différentes.

Utilisez Intl.getCanonicalLocales() lorsque vous avez besoin de :

  • Normaliser les identifiants de locale vers leur forme canonique
  • Valider et dédupliquer une liste d'identifiants de locale
  • Convertir une casse incohérente au format standard
  • Valider les identifiants de locale sans créer d'objets

Utilisez le constructeur Intl.Locale lorsque vous avez besoin de :

  • Valider un identifiant de locale et travailler immédiatement avec ses propriétés
  • Extraire des composants comme la langue, la région ou le script de l'identifiant
  • Créer un objet locale pour l'utiliser avec d'autres API Intl
  • Valider et manipuler des identifiants de locale ensemble

Le constructeur Intl.Locale est plus puissant car il crée un objet que vous pouvez interroger et modifier. Cependant, si vous avez seulement besoin de validation et de normalisation, Intl.getCanonicalLocales() est plus simple.

Validation des entrées utilisateur

Lors de l'acceptation d'identifiants de locale à partir des entrées utilisateur, validez-les avant de les utiliser dans votre application. Cela évite les erreurs et fournit un retour clair lorsque les utilisateurs saisissent des valeurs invalides.

function validateUserLocale(input) {
  try {
    const canonicalLocales = Intl.getCanonicalLocales(input);
    return {
      valid: true,
      locale: canonicalLocales[0]
    };
  } catch (error) {
    return {
      valid: false,
      error: "Veuillez saisir un identifiant de locale valide comme en-US ou fr-FR"
    };
  }
}

const result1 = validateUserLocale("en-US");
console.log(result1);
// Sortie: { valid: true, locale: "en-US" }

const result2 = validateUserLocale("english");
console.log(result2);
// Sortie: { valid: false, error: "Veuillez saisir un identifiant de locale..." }

Cette fonction valide l'entrée et renvoie soit la locale canonique, soit un message d'erreur convivial.

Validation des données de configuration

Les applications chargent souvent des identifiants de locale à partir de fichiers de configuration ou de variables d'environnement. Validez ces valeurs au démarrage de votre application pour détecter rapidement les erreurs de configuration.

function loadLocaleConfig(configLocales) {
  const validLocales = [];
  const invalidLocales = [];

  for (const locale of configLocales) {
    try {
      const canonical = Intl.getCanonicalLocales(locale);
      validLocales.push(canonical[0]);
    } catch (error) {
      invalidLocales.push(locale);
    }
  }

  if (invalidLocales.length > 0) {
    console.warn("Identifiants de locale invalides trouvés:", invalidLocales);
  }

  return validLocales;
}

const config = ["en-US", "fr-FR", "invalid", "es_MX", "de-DE"];
const locales = loadLocaleConfig(config);
console.log(locales);
// Sortie: ["en-US", "fr-FR", "de-DE"]
// Avertissement: Identifiants de locale invalides trouvés: ["invalid", "es_MX"]

Cette fonction filtre les identifiants de locale invalides et affiche un avertissement, permettant à l'application de continuer avec les locales valides.

Validation des réponses d'API

Lors de la réception d'identifiants de locale provenant d'API externes, validez-les avant de les utiliser dans votre application. Les API peuvent renvoyer des identifiants de locale dans des formats non standard ou avec des erreurs.

function processApiLocale(apiResponse) {
  const locale = apiResponse.preferredLocale;

  try {
    const validated = new Intl.Locale(locale);
    return {
      success: true,
      language: validated.language,
      region: validated.region,
      baseName: validated.baseName
    };
  } catch (error) {
    console.error("L'API a renvoyé une locale invalide:", locale);
    return {
      success: false,
      fallback: "en-US"
    };
  }
}

const response1 = { preferredLocale: "fr-CA" };
console.log(processApiLocale(response1));
// Sortie: { success: true, language: "fr", region: "CA", baseName: "fr-CA" }

const response2 = { preferredLocale: "invalid_locale" };
console.log(processApiLocale(response2));
// Sortie: { success: false, fallback: "en-US" }

Cette fonction valide la réponse de l'API et extrait des informations structurées sur la locale, ou fournit une valeur de repli si la locale est invalide.