Comment vérifier si un identifiant de locale est valide

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

Introduction

Lorsque votre application accepte des identifiants de locale provenant de saisies 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 du passage 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, d'écriture, de région et d'extension.

Les identifiants de locale valides utilisent des traits d'union pour séparer les composants, pas des underscores 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é tel qu'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 underscore au lieu d'un trait d'union)
  • english (code de langue non 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 standards reconnus.

Utiliser Intl.getCanonicalLocales pour valider

La méthode Intl.getCanonicalLocales() valide les identifiants de locale et les retourne 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);
// Output: ["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 retourne la forme canonique correcte :

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

Lorsque vous passez un identifiant de locale invalide, la méthode lève une RangeError :

try {
  Intl.getCanonicalLocales("en_US");
} catch (error) {
  console.error(error.name);
  // Output: "RangeError"
  console.error(error.message);
  // Output: "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.

Valider plusieurs identifiants de locale

La méthode Intl.getCanonicalLocales() accepte un tableau pour valider plusieurs identifiants de locale en une seule fois. La méthode retourne un tableau de formes canoniques pour tous les identifiants valides.

const locales = ["en-US", "fr-FR", "es-MX"];
const result = Intl.getCanonicalLocales(locales);
console.log(result);
// Output: ["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);
// Output: ["en-US"]

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

Si une locale du tableau est invalide, la méthode entière lève une erreur :

try {
  Intl.getCanonicalLocales(["en-US", "invalid", "fr-FR"]);
} catch (error) {
  console.error(error.message);
  // Output: "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.

Utiliser le constructeur Intl.Locale pour valider

Le constructeur Intl.Locale fournit une autre façon de valider les identifiants de locale. Lorsque vous créez un objet locale avec un identifiant invalide, le constructeur lève une RangeError.

try {
  const locale = new Intl.Locale("en-US");
  console.log("Valid locale");
} catch (error) {
  console.error("Invalid locale");
}
// Output: "Valid locale"

Le constructeur génère une erreur pour les identifiants invalides :

try {
  const locale = new Intl.Locale("en_US");
  console.log("Valid locale");
} catch (error) {
  console.error("Invalid locale");
  console.error(error.message);
}
// Output: "Invalid locale"
// Output: "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);
// Output: "en-US"

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

Les codes de langue en majuscules et en minuscules sont acceptés, et le constructeur les normalise vers la 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 devez :

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

Utilisez le constructeur Intl.Locale lorsque vous devez :

  • Valider un identifiant de locale et travailler immédiatement avec ses propriétés
  • Extraire des composants comme la langue, la région ou l'écriture de l'identifiant
  • Créer un objet locale pour l'utiliser avec d'autres API Intl
  • Valider et manipuler les 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.

Valider les entrées utilisateur

Lorsque vous acceptez des identifiants de locale provenant d'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: "Please enter a valid locale identifier like en-US or fr-FR"
    };
  }
}

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

const result2 = validateUserLocale("english");
console.log(result2);
// Output: { valid: false, error: "Please enter a valid locale..." }

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

Valider les données de configuration

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

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("Invalid locale identifiers found:", invalidLocales);
  }

  return validLocales;
}

const config = ["en-US", "fr-FR", "invalid", "es_MX", "de-DE"];
const locales = loadLocaleConfig(config);
console.log(locales);
// Output: ["en-US", "fr-FR", "de-DE"]
// Warning: Invalid locale identifiers found: ["invalid", "es_MX"]

Cette fonction filtre les identifiants de locale invalides et enregistre 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 contenant 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("API returned invalid locale:", locale);
    return {
      success: false,
      fallback: "en-US"
    };
  }
}

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

const response2 = { preferredLocale: "invalid_locale" };
console.log(processApiLocale(response2));
// Output: { 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.