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

المقدمة

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

تساعد عملية التحقق على التأكد من أن السلاسل مثل 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);
// Output: ["en-US"]

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

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

إذا قمت بتمرير معرف إعداد محلي غير صحيح، ستقوم الطريقة بإلقاء 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"
}

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

التحقق من عدة معرفات إعداد محلي في آن واحد

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

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

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

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

تمثل القيم الثلاثة جميعها نفس الإعداد المحلي، لذا تُرجع الطريقة قيمة قياسية واحدة فقط.

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

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

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

التحقق من صحة ردود API

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

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

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