كيفية التحقق من صحة معرّف اللغة

مقدمة

عندما يقبل تطبيقك معرّفات اللغة المحلية من إدخال المستخدم، أو استجابات واجهة برمجة التطبيقات، أو ملفات التكوين، تحتاج إلى التحقق من صحتها قبل استخدامها. سيتسبب معرّف اللغة المحلية غير الصالح في حدوث أخطاء في وظائف التنسيق أو إنتاج نتائج غير متوقعة.

يضمن التحقق من الصحة أن السلاسل النصية مثل en-US صحيحة هيكلياً وفقاً للمعايير الدولية. هذا يمنع أخطاء وقت التشغيل عند تمرير معرّفات اللغة المحلية إلى واجهة برمجة التطبيقات Intl أو مكتبات التدويل الأخرى.

توفر جافا سكريبت طريقتين مدمجتين للتحقق من صحة معرّفات اللغة المحلية. تتحقق كلتا الطريقتين من بنية المعرّف وفقاً لمعيار BCP 47، الذي يحدد تنسيق علامات اللغة.

ما الذي يجعل معرّف اللغة المحلية صالحاً

يتبع معرّف اللغة المحلية معيار BCP 47 لعلامات اللغة. يحدد هذا المعيار الهيكل والقواعد لدمج مكونات اللغة والنص والمنطقة والامتداد.

تستخدم معرّفات اللغة المحلية الصالحة الواصلات لفصل المكونات، وليس الشرطات السفلية أو الأحرف الأخرى. يجب أن يكون رمز اللغة رمزاً معترفاً به وفقاً لمعيار ISO 639، ويجب أن تكون رموز المناطق رموزاً معترفاً بها وفقاً لمعيار ISO 3166-1.

أمثلة على معرّفات اللغة المحلية الصالحة:

• en (الإنجليزية)
• en-US (الإنجليزية الأمريكية)
• zh-Hans (الصينية المبسطة)
• zh-Hans-CN (الصينية المبسطة كما تُستخدم في الصين)
• en-US-u-ca-gregory (الإنجليزية الأمريكية مع التقويم الغريغوري)

أمثلة على معرّفات اللغة المحلية غير الصالحة:

• en_US (يستخدم الشرطة السفلية بدلاً من الواصلة)
• english (ليس رمز لغة معترفاً به)
• en-USA (يجب أن يكون رمز المنطقة حرفين، وليس ثلاثة)
• EN-us (يجب أن يكون رمز اللغة بأحرف صغيرة)
• abc-XY (رمز اللغة غير موجود)

تتحقق طرق التحقق من الصحة من هذه القواعد الهيكلية وتتأكد من أن الرموز معترف بها كمعايير.

استخدام Intl.getCanonicalLocales للتحقق من الصحة

تقوم طريقة Intl.getCanonicalLocales() بالتحقق من صحة معرفات اللغة المحلية وإرجاعها بشكلها القياسي. تقبل هذه الطريقة معرف لغة محلية واحد أو مصفوفة من المعرفات.

const result = Intl.getCanonicalLocales("en-US");
console.log(result);
// الناتج: ["en-US"]

تقوم الطريقة بتطبيع الإدخال عن طريق تحويله إلى التنسيق القياسي. حتى إذا قمت بتمرير معرف لغة محلية بحالة أحرف غير صحيحة، فإنها تُرجع الشكل القياسي الصحيح:

const result = Intl.getCanonicalLocales("EN-us");
console.log(result);
// الناتج: ["en-US"]

عندما تقوم بتمرير معرف لغة محلية غير صالح، تطرح الطريقة خطأ RangeError:

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

يشير هذا الخطأ إلى أن المعرف لا يتبع بنية BCP 47. يمكنك التقاط هذا الخطأ للتعامل مع الإدخال غير الصالح بشكل سلس.

التحقق من صحة معرفات لغات متعددة

تقبل طريقة Intl.getCanonicalLocales() مصفوفة للتحقق من صحة معرفات لغات متعددة دفعة واحدة. تُرجع الطريقة مصفوفة من الأشكال القياسية لجميع المعرفات الصالحة.

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

تقوم الطريقة أيضًا بإزالة معرفات اللغات المكررة من النتيجة:

const locales = ["en-US", "EN-us", "en-US"];
const result = Intl.getCanonicalLocales(locales);
console.log(result);
// الناتج: ["en-US"]

تمثل قيم الإدخال الثلاثة نفس اللغة المحلية، لذلك تُرجع الطريقة شكلًا قياسيًا واحدًا فقط.

إذا كانت أي لغة محلية في المصفوفة غير صالحة، فإن الطريقة بأكملها تطرح خطأ:

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

عند التحقق من قوائم مقدمة من المستخدم، تحقق من صحة كل لغة محلية بشكل فردي لتحديد المعرفات المحددة غير الصالحة.

استخدام منشئ Intl.Locale للتحقق من الصحة

يوفر منشئ Intl.Locale طريقة أخرى للتحقق من صحة معرفات اللغة المحلية. عندما تقوم بإنشاء كائن لغة محلية بمعرف غير صالح، يقوم المنشئ بإلقاء خطأ RangeError.

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

يلقي المنشئ خطأً للمعرفات غير الصالحة:

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"

على عكس Intl.getCanonicalLocales()، لا يقوم منشئ Intl.Locale بتطبيع حالة الأحرف. فهو يتطلب أن يستخدم المعرف حالة الأحرف الصحيحة:

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"

يتم قبول رموز اللغة بالأحرف الكبيرة والصغيرة، ويقوم المنشئ بتطبيعها إلى الشكل القياسي.

اختيار طريقة التحقق من الصحة

تخدم كلتا طريقتي التحقق أغراضًا مختلفة وتوفر ميزات مختلفة.

استخدم Intl.getCanonicalLocales() عندما تحتاج إلى:

• تطبيع معرفات اللغة المحلية إلى شكلها القياسي
• التحقق من صحة قائمة معرفات اللغة المحلية وإزالة التكرار منها
• تحويل حالة الأحرف غير المتسقة إلى التنسيق القياسي
• التحقق من صحة معرفات اللغة المحلية دون إنشاء كائنات

استخدم منشئ Intl.Locale عندما تحتاج إلى:

• التحقق من صحة معرف لغة محلية والعمل فورًا مع خصائصه
• استخراج مكونات مثل اللغة أو المنطقة أو النص من المعرف
• إنشاء كائن لغة محلية للاستخدام مع واجهات برمجة تطبيقات Intl الأخرى
• التحقق من صحة معرفات اللغة المحلية ومعالجتها معًا

منشئ Intl.Locale أكثر قوة لأنه ينشئ كائنًا يمكنك الاستعلام عنه وتعديله. ومع ذلك، إذا كنت تحتاج فقط إلى التحقق من الصحة والتطبيع، فإن Intl.getCanonicalLocales() أبسط.

التحقق من صحة مدخلات المستخدم

عند قبول معرفات اللغة المحلية من مدخلات المستخدم، تحقق من صحتها قبل استخدامها في تطبيقك. هذا يمنع الأخطاء ويوفر تعليقات واضحة عندما يدخل المستخدمون قيمًا غير صالحة.

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..." }

تتحقق هذه الدالة من صحة المدخلات وتعيد إما اللغة المحلية القانونية أو رسالة خطأ سهلة الفهم للمستخدم.

التحقق من صحة بيانات التكوين

غالبًا ما تقوم التطبيقات بتحميل معرفات اللغة المحلية من ملفات التكوين أو متغيرات البيئة. تحقق من صحة هذه القيم عند بدء تشغيل تطبيقك لاكتشاف أخطاء التكوين مبكرًا.

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"]

تقوم هذه الدالة بتصفية معرفات اللغة المحلية غير الصالحة وتسجيل تحذير، مما يسمح للتطبيق بالاستمرار مع اللغات المحلية الصالحة.

التحقق من صحة استجابات واجهة برمجة التطبيقات

عند استلام معرفات اللغة المحلية من واجهات برمجة التطبيقات الخارجية، تحقق من صحتها قبل استخدامها في تطبيقك. قد تعيد واجهات برمجة التطبيقات معرفات اللغة المحلية بتنسيقات غير قياسية أو مع أخطاء.

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" }

تتحقق هذه الدالة من صحة استجابة واجهة برمجة التطبيقات وتستخرج معلومات منظمة حول اللغة المحلية، أو توفر قيمة احتياطية إذا كانت اللغة المحلية غير صالحة.