انتقل إلى المحتوى الرئيسي

المقدمة

استرجع اللغات المكونة في مشروعك لدعم المحتوى متعدد اللغات واكتشاف المواقع.

مزيد من المعلومات حول واجهة مستخدم الوحدة https://doc.oneentry.cloud/docs/category/languages

🎯 ماذا تفعل هذه الوحدة؟​

تتيح لك وحدة Locales استرجاع اللغات النشطة المكونة في مشروع OneEntry الخاص بك - حتى تتمكن من بناء تطبيقات دولية تقدم محتوى بعدة لغات.

بدلاً من ترميز اللغات بشكل ثابت في تطبيقك، يمكنك استرجاع قائمة اللغات النشطة من OneEntry بشكل ديناميكي، مما يسمح لمحتواك بالتكيف مع المواقع التي قمت بتمكينها (الإنجليزية، الروسية، العربية، الإسبانية، إلخ). يتم تكوين اللغات في لوحة إدارة OneEntry؛ وواجهة برمجة التطبيقات (SDK) للقراءة فقط وتقوم فقط باسترجاع اللغات.

🚀 البدء السريع​

قم بتهيئة الوحدة من defineOneEntry:


const { Locales } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

استرجع المواقع النشطة واقرأ حقولها:

// Returns only active locales (isActive: true).
const locales = await Locales.getLocales();

console.log(`${locales.length} active languages`);

locales.forEach((locale) => {
  console.log(locale.code, locale.name, locale.shortCode);
});

✨ المفاهيم الأساسية​

ما هو الموقع؟​

الموقع locale هو مزيج من اللغة والمنطقة يحدد كيفية عرض المحتوى:

  • رمز اللغة - رمز اللغة ISO 639-1 (مثل: en, ru, ar)
  • رمز المنطقة - رمز الدولة ISO 3166-1 (مثل: US, GB, RU)
  • معرف الموقع - تنسيق مركب: language_REGION (مثل: en_US, ru_RU, ar_SA)

أمثلة:

رمز الموقعاللغةالمنطقةالوصف
en_USالإنجليزيةالولايات المتحدةالإنجليزية الأمريكية
en_GBالإنجليزيةبريطانيا العظمىالإنجليزية البريطانية
ru_RUالروسيةروسياالروسية
es_ESالإسبانيةإسبانياالإسبانية الأوروبية
es_MXالإسبانيةالمكسيكالإسبانية المكسيكية
ar_SAالعربيةالمملكة العربية السعوديةالعربية (المملكة العربية السعودية)
fr_FRالفرنسيةفرنساالفرنسية
de_DEالألمانيةألمانياالألمانية

هيكل الموقع​

كل موقع يتم إرجاعه بواسطة getLocales() (ILocalEntity) يحتوي على:

{
  id: 146,                      // unique ID
  shortCode: 'en',              // short code
  code: 'en_US',                // full code
  name: 'English (USA)',        // name
  nativeName: 'English (USA)',  // native name
  isActive: true,               // is active (always true here)
  image: null,                  // image
  position: 1,                  // position
}

رمز الموقع مقابل الرمز القصير​

كل موقع له تنسيقين للرمز:

الحقلالتنسيقالمثالالاستخدام
codelanguage_REGIONen_US, ru_RUتحديد الموقع بالكامل
shortCodelanguageen, ruتحديد اللغة فقط

📋 ما تحتاج إلى معرفته​

يتم تكوين المواقع في لوحة الإدارة (للقراءة فقط)​

لا يمكنك إنشاء أو تحديث أو حذف المواقع عبر واجهة برمجة التطبيقات - يتم تكوينها في لوحة إدارة OneEntry:

OneEntry Admin Panel → Settings → Languages → Add Language → Select Locale

واجهة برمجة التطبيقات مخصصة فقط لـ استرجاع معلومات المواقع.

واجهة برمجة التطبيقات تعيد فقط المواقع النشطة​

getLocales() تعيد فقط كائنات الترجمة اللغوية النشطة (isActive: true). المواقع غير النشطة المكونة في لوحة الإدارة لا يتم إرجاعها، لذا لا حاجة لتصفية هذه المواقع على العميل. كل موقع يتم إرجاعه يحمل أيضًا علامة isActive (دائمًا true هنا)، إلى جانب code و shortCode و name و nativeName و image و position.

لا يوجد حقل للموقع الافتراضي في الاستجابة - اختر واحتفظ بلغة احتياطية في تطبيقك الخاص.

📊 جدول مرجعي سريع​

الطريقةالوصفحالة الاستخدام
getLocales()الحصول على جميع المواقع النشطةاسترجاع اللغات المتاحة

❓ الأسئلة الشائعة (FAQ)​

كيف أضيف لغات جديدة إلى مشروعي؟​

لا يمكنك إضافة مواقع عبر واجهة برمجة التطبيقات. يتم تكوين المواقع في لوحة إدارة OneEntry.

هل تعيد getLocales() اللغات غير النشطة؟​

لا. واجهة برمجة التطبيقات تعيد فقط المواقع النشطة (isActive: true). اللغات المعطلة في لوحة الإدارة غير مدرجة في الاستجابة.

هل يمكنني تخزين المواقع في الذاكرة المؤقتة؟​

نعم. المواقع نادرًا ما تتغير، لذا يُوصى بتخزين النتيجة في الذاكرة المؤقتة لتحسين الأداء.

كيف أتعامل مع الترجمات المفقودة؟​

اختر لغة احتياطية في تطبيقك وارجع إليها عندما يكون المحتوى مفقودًا للموقع المطلوب - getLocales() لا تتضمن حقل الموقع الافتراضي.

🎓 أفضل الممارسات​

  • اعتمد على القائمة النشطة - واجهة برمجة التطبيقات تعيد بالفعل فقط المواقع المفعلة، لذا لا حاجة لتصفية على جانب العميل.
  • قم بتخزين المواقع في الذاكرة المؤقتة - نادرًا ما تتغير؛ قم بتخزين النتيجة لتحسين الأداء.
  • اختر لغتك الاحتياطية الخاصة - لا يوجد حقل للموقع الافتراضي؛ تعامل مع الترجمات المفقودة في تطبيقك.
  • طابق بين code و shortCode - استخدم code (en_US) للتحديد الكامل و shortCode (en) للمنطق الخاص باللغة فقط.

🔗 الوثائق ذات الصلة​