واجهة برمجة التطبيقات Intl.Locale

تحليل وتعديل والاستعلام عن معرفات اللغات المحلية باستخدام كائنات جافاسكريبت منظمة

مقدمة

عند بناء تطبيقات للغات ومناطق متعددة، ستواجه معرّفات اللغة المحلية مثل en-US وfr-FR أو zh-Hans-CN. تظهر هذه السلاسل النصية في واجهات برمجة التطبيقات للمتصفح، ورؤوس HTTP، وتفضيلات المستخدم. وهي ترمز إلى معلومات حول اللغة والمنطقة ونظام الكتابة وتفضيلات التنسيق.

تقوم واجهة برمجة التطبيقات Intl.Locale بتحويل هذه السلاسل النصية الغامضة إلى كائنات منظمة يمكنك فحصها والتعامل معها. بدلاً من تحليل السلاسل النصية يدويًا أو تخمين ما يعنيه zh-Hans-CN، يمكنك إنشاء كائن لغة محلية وقراءة خصائصه مباشرة.

يشرح هذا الدليل كيفية عمل معرّفات اللغة المحلية، وكيفية استخدام واجهة برمجة التطبيقات Intl.Locale للعمل معها، ومتى تساعد كائنات اللغة المحلية المنظمة في حل المشكلات الحقيقية.

فهم معرّفات اللغة المحلية

معرّف اللغة المحلية هو سلسلة نصية تحدد التفضيلات الثقافية لتنسيق التواريخ والأرقام والعملات والنصوص. يحتوي المعرّف على مكونات متعددة مفصولة بواسطة شرطات.

الهيكل الأكثر شيوعًا يتبع معيار BCP 47:

language-script-region-variant-extensions

كل مكون اختياري باستثناء رمز اللغة.

رموز اللغات

تستخدم رموز اللغات حرفين أو ثلاثة أحرف من معيار ISO 639. أمثلة شائعة:

  • en للإنجليزية
  • es للإسبانية
  • fr للفرنسية
  • de للألمانية
  • ja لليابانية
  • zh للصينية
  • ar للعربية

رمز اللغة دائمًا بأحرف صغيرة ويظهر أولاً في المعرّف.

رموز المناطق

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

  • en-US للإنجليزية الأمريكية
  • en-GB للإنجليزية البريطانية
  • es-ES للإسبانية الأوروبية
  • es-MX للإسبانية المكسيكية
  • fr-FR للفرنسية كما تُتحدث في فرنسا
  • fr-CA للفرنسية الكندية

تغير رموز المناطق اتفاقيات التنسيق. تستخدم الإنجليزية الأمريكية تواريخ بصيغة MM/DD/YYYY، بينما تستخدم الإنجليزية البريطانية صيغة DD/MM/YYYY.

رموز النصوص

رموز النصوص تحدد نظام الكتابة باستخدام أربعة أحرف مع كتابة الحرف الأول بحرف كبير. وهي مهمة للغات التي تُكتب بعدة نصوص:

  • zh-Hans للصينية المبسطة
  • zh-Hant للصينية التقليدية
  • sr-Cyrl للصربية بالأبجدية السيريلية
  • sr-Latn للصربية بالأبجدية اللاتينية

معظم اللغات المحلية تحذف رمز النص لأن اللغة تتضمن نصًا افتراضيًا. الإنجليزية تستخدم النص اللاتيني افتراضيًا، لذلك تكتب en بدلاً من en-Latn.

علامات الامتداد

علامات الامتداد تضيف تفضيلات التنسيق إلى معرفات اللغات المحلية. تبدأ بـ -u- متبوعة بأزواج المفتاح والقيمة:

en-US-u-ca-gregory-nu-latn-hc-h12

مفاتيح الامتداد الشائعة:

  • ca لنظام التقويم (gregory، buddhist، islamic)
  • nu لنظام الترقيم (latn، arab، hanidec)
  • hc لدورة الساعة (h12، h23، h11، h24)

الامتدادات تخصص كيفية عرض المنسقات للبيانات دون تغيير اللغة أو المنطقة.

إنشاء كائنات اللغة المحلية

منشئ Intl.Locale يقبل سلسلة معرف اللغة المحلية ويعيد كائنًا منظمًا:

const locale = new Intl.Locale("en-US");

console.log(locale.language); // "en"
console.log(locale.region); // "US"

يمكنك أيضًا تمرير كائن خيارات لتجاوز أو إضافة خصائص:

const locale = new Intl.Locale("en", {
  region: "GB",
  hourCycle: "h23"
});

console.log(locale.baseName); // "en-GB"
console.log(locale.hourCycle); // "h23"

المنشئ يرمي RangeError إذا كان المعرف غير صالح:

try {
  const invalid = new Intl.Locale("invalid-locale-code");
} catch (error) {
  console.error(error.message); // "invalid language subtag: invalid"
}

هذا التحقق يضمن اكتشاف معرفات اللغة المحلية المشوهة قبل تمريرها إلى المنسقات.

قراءة خصائص اللغة المحلية

كائنات اللغة المحلية تكشف عن خصائص تتوافق مع مكونات سلسلة المعرف. جميع الخصائص للقراءة فقط.

الخصائص الأساسية

تُرجع خاصية language رمز اللغة:

const locale = new Intl.Locale("fr-CA");
console.log(locale.language); // "fr"

تُرجع خاصية region رمز المنطقة:

const locale = new Intl.Locale("fr-CA");
console.log(locale.region); // "CA"

تُرجع خاصية script رمز النص إذا كان موجودًا:

const locale = new Intl.Locale("zh-Hans-CN");
console.log(locale.script); // "Hans"

تُرجع خاصية baseName المعرّف الأساسي الكامل بدون امتدادات:

const locale = new Intl.Locale("en-US-u-ca-gregory-nu-latn");
console.log(locale.baseName); // "en-US"

استخدم baseName عندما تحتاج إلى اللغة والمنطقة ولكن تريد تجاهل تفضيلات التنسيق.

خصائص الامتداد

تُرجع خصائص الامتداد قيمًا من علامة الامتداد -u- أو undefined إذا لم يتم تحديدها.

تُرجع خاصية calendar نظام التقويم:

const locale = new Intl.Locale("ar-SA-u-ca-islamic");
console.log(locale.calendar); // "islamic"

تُرجع خاصية numberingSystem نظام الترقيم:

const locale = new Intl.Locale("ar-EG-u-nu-arab");
console.log(locale.numberingSystem); // "arab"

تُرجع خاصية hourCycle تفضيل دورة الساعة:

const locale = new Intl.Locale("en-US-u-hc-h23");
console.log(locale.hourCycle); // "h23"

تُرجع خاصية caseFirst تفضيل حالة الترتيب:

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

تشير خاصية numeric إلى ما إذا كان الترتيب الرقمي مُمكّنًا:

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

تتيح لك هذه الخصائص فحص تفضيلات التنسيق دون تحليل سلسلة الامتداد يدويًا.

الاستعلام عن معلومات اللغة المحلية

توفر واجهة برمجة التطبيقات Intl.Locale طرقًا تُرجع مصفوفات من الخيارات المتاحة للغة المحلية. تساعد هذه الطرق في بناء واجهات المستخدم والتحقق من صحة خيارات التنسيق.

التقويمات المتاحة

تُرجع طريقة getCalendars() أنظمة التقويم المستخدمة بشكل شائع للغة المحلية:

const locale = new Intl.Locale("th-TH");
const calendars = locale.getCalendars();
console.log(calendars); // ["buddhist", "gregory"]

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

التصنيفات المتاحة

تُرجع طريقة getCollations() أنواع التصنيف لترتيب السلاسل النصية:

const locale = new Intl.Locale("de-DE");
const collations = locale.getCollations();
console.log(collations); // ["phonebk", "emoji", "eor"]

تمتلك اللغة الألمانية تصنيفًا للدليل الهاتفي يقوم بترتيب السلاسل النصية بشكل مختلف عن التصنيف القياسي ليونيكود.

دورات الساعات المتاحة

تُرجع طريقة getHourCycles() تنسيقات دورة الساعة:

const locale = new Intl.Locale("en-US");
const hourCycles = locale.getHourCycles();
console.log(hourCycles); // ["h12"]

تستخدم اللغة الإنجليزية الأمريكية نظام الـ 12 ساعة افتراضيًا. العديد من اللغات الأخرى تُرجع ["h23"] لنظام الـ 24 ساعة.

أنظمة الترقيم المتاحة

تُرجع طريقة getNumberingSystems() أنظمة الترقيم المستخدمة بشكل شائع للغة المحلية:

const locale = new Intl.Locale("ar-EG");
const numberingSystems = locale.getNumberingSystems();
console.log(numberingSystems); // ["arab", "latn"]

اللغات العربية غالبًا ما تدعم كلاً من الأرقام العربية والأرقام اللاتينية.

اتجاه النص

تُرجع طريقة getTextInfo() معلومات ترتيب النص:

const locale = new Intl.Locale("ar-SA");
const textInfo = locale.getTextInfo();
console.log(textInfo.direction); // "rtl"

اللغات التي تُكتب من اليمين إلى اليسار مثل العربية والعبرية تُرجع "rtl". اللغات التي تُكتب من اليسار إلى اليمين تُرجع "ltr".

اصطلاحات الأسبوع

تُرجع طريقة getWeekInfo() بنية الأسبوع للغة المحلية:

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

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

المناطق الزمنية

تُرجع طريقة getTimeZones() المناطق الزمنية لمنطقة اللغة المحلية:

const locale = new Intl.Locale("en-US");
const timeZones = locale.getTimeZones();
console.log(timeZones); // ["America/New_York", "America/Chicago", ...]

تُرجع هذه الطريقة معرفات المناطق الزمنية IANA لرمز المنطقة.

تعظيم معرفات اللغة المحلية

تضيف طريقة maximize() العلامات الفرعية المحتملة لإنشاء معرّف كامل. فهي تستنتج رموز النصوص والمناطق المفقودة بناءً على بيانات اللغة.

عندما تحدد رمز لغة فقط، تضيف maximize() النص والمنطقة الأكثر شيوعًا:

const locale = new Intl.Locale("en");
const maximized = locale.maximize();
console.log(maximized.baseName); // "en-Latn-US"

تكون اللغة الإنجليزية افتراضيًا بالنص اللاتيني ومنطقة الولايات المتحدة لأنها الارتباطات الأكثر شيوعًا.

تعتمد تعظيم اللغة الصينية على النص:

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"

ترتبط الصينية المبسطة بالصين، بينما ترتبط الصينية التقليدية بتايوان.

استخدم maximize() عند تطبيع إدخال المستخدم أو مقارنة معرّفات اللغة المحلية. فهي تجعل المعلومات الضمنية صريحة.

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

تزيل طريقة minimize() العلامات الفرعية الزائدة لإنشاء أقصر معرّف مكافئ. فهي تزيل رموز النصوص والمناطق عندما تتطابق مع الإعدادات الافتراضية المحتملة.

عندما تستخدم اللغة المحلية النص والمنطقة الافتراضيين، تزيلهما minimize():

const locale = new Intl.Locale("en-Latn-US");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en"

النص اللاتيني ومنطقة الولايات المتحدة هما الإعدادات الافتراضية للغة الإنجليزية، لذا يمكن إزالتهما دون فقدان المعلومات.

بالنسبة للغات المحلية ذات المناطق غير الافتراضية، تحتفظ minimize() بالمنطقة:

const locale = new Intl.Locale("en-Latn-GB");
const minimized = locale.minimize();
console.log(minimized.baseName); // "en-GB"

تحتاج الإنجليزية البريطانية إلى رمز المنطقة لأنها تختلف عن الإعداد الافتراضي.

استخدم minimize() لإنشاء معرّفات مضغوطة للتخزين أو عناوين URL مع الحفاظ على المعنى.

التحويل إلى سلاسل نصية

تُرجع طريقة toString() معرّف اللغة المحلية الكامل بما في ذلك الامتدادات:

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"

التمثيل النصي صالح للتمرير إلى واجهات برمجة تطبيقات Intl الأخرى أو التخزين كبيانات تكوين.

يمكنك أيضًا تحويل كائنات اللغة المحلية إلى سلاسل نصية بشكل ضمني:

const locale = new Intl.Locale("fr-FR");
const formatter = new Intl.DateTimeFormat(locale);

يقبل مُنشئ DateTimeFormat كائنات اللغة المحلية مباشرة ويستدعي toString() داخليًا.

حالات الاستخدام العملية

تحل واجهة برمجة التطبيقات Intl.Locale العديد من المشكلات الشائعة عند بناء التطبيقات المدعومة بالتدويل.

بناء أدوات اختيار اللغة المحلية

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

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

التحقق من صحة إدخال اللغة المحلية

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

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

استخراج اللغة للبدائل الاحتياطية

عند تنفيذ سلاسل البدائل الاحتياطية للغة، استخرج رمز اللغة بدون المنطقة:

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

هذا ينشئ سلسلة بدائل احتياطية تحاول استخدام اللغة المحلية المحددة، ثم اللغة بدون المنطقة، ثم اللغة الافتراضية.

تكوين المنسقات

استخدم كائنات اللغة لتكوين منسقات Intl بتفضيلات محددة:

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"

اكتشاف تفضيلات المستخدم

توفر واجهات برمجة التطبيقات للمتصفح سلاسل لغوية يمكنك تحليلها لفهم تفضيلات المستخدم:

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

هذا ينشئ ملفًا تعريفيًا لتفضيلات المستخدم بناءً على إعدادات المتصفح الخاصة بهم.

دعم المتصفح

تعمل واجهة برمجة التطبيقات Intl.Locale في جميع المتصفحات الحديثة. توفر Chrome وFirefox وSafari وEdge دعمًا كاملاً للمنشئ والخصائص والطرق الموصوفة في هذا الدليل.

تتطلب الطرق الأحدث مثل getCalendars() وgetCollations() وgetHourCycles() وgetNumberingSystems() وgetTextInfo() وgetTimeZones() وgetWeekInfo() إصدارات حديثة من المتصفح. تحقق من جداول توافق المتصفح قبل استخدام هذه الطرق إذا كنت تدعم متصفحات أقدم.

يدعم Node.js واجهة برمجة التطبيقات Intl.Locale بدءًا من الإصدار 12، مع دعم كامل للطرق في الإصدار 18 وما بعده.

الملخص

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

المفاهيم الأساسية:

  • تحتوي معرفات اللغة على مكونات اللغة والنص والمنطقة والامتداد
  • ينشئ منشئ Intl.Locale كائنات ويتحقق من صحة المعرفات
  • توفر خصائص مثل language وregion وcalendar وصولاً منظمًا
  • تعيد طرق مثل getCalendars() وgetHourCycles() الخيارات المتاحة
  • تقوم طرق maximize() وminimize() بتطبيع المعرفات
  • تعمل كائنات اللغة مباشرة مع واجهات برمجة تطبيقات Intl الأخرى

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