كيفية الاستعلام عن المحتوى متعدد اللغات باستخدام WPGraphQL – تصفية اللغة والترجمات

قبل أن تبدأ

ثبّت وفعّل هذه الإضافات:

• WPGraphQL (الإضافة مفتوحة المصدر من مشروع WPGraphQL).
• WPML و WPML ترجمة النصوص.
• WPML GraphQL (الملحق الذي تغطيه هذه الصفحة).

إذا كنت تستخدم أيضاً Advanced Custom Fields:

• Advanced Custom Fields Multilingual (ACFML).
• WPGraphQL for Advanced Custom Fields (من مشروع WPGraphQL).

يجب ترجمة محتواك المصدر في WPML قبل أن تُرجع الاستعلامات أدناه أي شيء. عند تفعيل ترجم كل شيء تلقائيًا (الإعداد الافتراضي في WPML 5)، يتم إنتاج الترجمات في الخلفية أثناء نشرك للمحتوى. للإعداد اليدوي، أرسل المحتوى للترجمة من WPML ← الترجمات ← لوحة التحكم. المقالات والمصطلحات المترجمة هي ما تقوم استعلامات GraphQL أدناه بتصفيته وإرجاعه.

بيئة التطوير المتكاملة GraphQL IDE – مكان اختبار الاستعلامات

يضيف WPGraphQL شاشة GraphQL ← GraphQL IDE إلى لوحة تحكم WordPress. يسرد منشئ الاستعلامات (Query Composer) في بيئة التطوير المتكاملة كل حقل متاح، بما في ذلك وسيطة language وحقل translations الخاصين بـ WPML، ويقوم بتشغيل الاستعلامات على موقعك المباشر. اختبر الاستعلامات هناك قبل ربطها في إطار عمل الواجهة الأمامية الخاص بك.

نقطة نهاية GraphQL لكل لغة

يستجيب WPGraphQL على /graphql. يُرجع الاستعلام الذي لا يحتوي على وسيطة language المحتوى بلغتك الافتراضية. للحصول على محتوى بلغة أخرى، أضف where: { language: "es" } إلى الاستعلام.

الاستعلام عن المحتوى حسب اللغة

أضف where: { language: "<code>" } إلى أي استعلام قائمة: المقالات، أنواع المنشورات المخصصة، مصطلحات التصنيف، القوائم، عناصر القائمة، التعليقات. رمز اللغة هو نفس الرمز الذي يستخدمه WPML في كل مكان (en، es، fr، pt-pt، وما إلى ذلك). مرّر language: "all" لإرجاع المحتوى من كل اللغات في وقت واحد.

query PostsES {
  posts(where: { language: "es" }) {
    nodes {
      slug
      uri
      categories {
        nodes { name }
      }
    }
  }
}

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

جلب كل ترجمة لعقدة في استعلام واحد

أضف حقل translations إلى أي استعلام مقالة أو تصنيف لإرجاع إصدارات العقدة باللغات الأخرى في نفس الاستجابة (payload):

query PostsWithTranslations {
  posts(where: { language: "en" }) {
    nodes {
      slug
      uri
      language { code }
      translations {
        slug
        uri
        language { code }
      }
    }
  }
}

تعود كل مقالة بحقولها الإنجليزية بالإضافة إلى مصفوفة من المعرّفات النصية للروابط (slugs) وعناوين URI الخاصة بها باللغات الأخرى. هذا هو الشكل الذي يستخدمه مبدل اللغة المعروض بجوار محتوى الصفحة: طلب واحد، وكل بديل يمكن للزائر التبديل إليه.

الاستعلام عن مقالة معينة بواسطة المعرف أو المعرّف النصي للرابط بأي لغة

لجلب مقالة مترجمة واحدة مباشرة (بواسطة المعرّف النصي للرابط المترجم أو بواسطة معرف قاعدة البيانات)، استخدم استعلام post المفرد مع idType:

query PostBySlug {
  post(id: "hola-mundo", idType: SLUG) {
    title
    slug
    uri
    language { code }
  }
}

query PostById {
  post(id: "2", idType: DATABASE_ID) {
    title
    slug
    uri
    language { code }
  }
}

يُرجع كلا الاستعلامين المقالة المترجمة (العنوان، المعرّف النصي للرابط، URI) دون مزيد من التصفية في الواجهة الأمامية.

القوائم متعددة اللغات

استعلم عن القوائم وعناصر القائمة حسب اللغة باستخدام نفس وسيطة where: { language }. للحصول على عناصر موقع قائمة القالب، أضف الموقع أيضاً:

query NavES {
  menuItems(where: { language: "es", location: PRIMARY }) {
    nodes {
      label
      url
      path
    }
  }
}

لسرد قوائم لغة ما، استخدم استعلام menus:

query MenusES {
  menus(where: { language: "es" }) {
    nodes {
      name
      locations
    }
  }
}

يعود label و url لكل عنصر قائمة باللغة المستعلم عنها. عناصر القائمة التي ترتبط بمقالات مترجمة تتحلل إلى URI المترجم تلقائياً. لا يحتوي استعلام menu المفرد على وسيطة language، لذا استخدم menus أو menuItems لاختيار اللغة.

اللغات المثبتة – لمبدل اللغة

لمبدل لغة عام (مستقل عن أي مقالة مفردة)، استخدم استعلامي languages و defaultLanguage لسرد كل لغة على الموقع:

query SiteLanguages {
  languages {
    code
    country_flag_url
    default_locale
    native_name
    translated_name
    url
  }
  defaultLanguage {
    code
    native_name
  }
}

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

الاستعلام عن الحقول المخصصة لـ ACF حسب اللغة

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

بالنسبة إلى ACF Options Pages، والتي لا ترتبط بمقالة واحدة، أضف وسيطة language إلى استعلام صفحة الخيارات:

query Settings {
  myOptionPage(language: "de") {
    addressFieldGroup {
      addressTitle
      repeaterAddressDetails { addressDetails }
    }
  }
}

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

منذ الإصدار 3.0.0 من WPGraphQL for ACF، لا تكون صفحة الخيارات موجودة في مخطط GraphQL إلا عند تفعيل show_in_graphql لها. بدونها، لن يكون استعلام صفحة الخيارات ووسيطة language الخاصة به موجودين. إذا قمت بتسجيل صفحة الخيارات في الكود، أضف الإعداد هناك:

acf_add_options_page( array(
  'page_title'         => 'Site Settings',
  'menu_slug'          => 'site-settings',
  'show_in_graphql'    => true,
  'graphql_field_name' => 'siteSettings',
) );

تفاصيل المؤلف المترجمة

يُرجع WPML GraphQL firstName، و lastName، و nickname، و description المترجمة للمستخدمين. لترجمتها:

1. اذهب إلى صفحة WPML ← ترجمة النصوص.
2. في خيار Translate User properties، حدد أدوار المستخدمين واحفظ.
3. ترجم السلاسل النصية في نطاق Authors.

القيود المعروفة والحلول البديلة المؤقتة

• عناوين URI المترجمة في بعض أشكال الاستعلامات. عند جلب مقالة مترجمة بواسطة URI (contentNode(id: "/de/some-slug/", idType: URI))، تحقق من أن URI المُرجع يطابق ما هو منشور في اللغة – تُرجع بعض أشكال الاستعلامات مسارات غير متسقة. اختبر في GraphQL IDE قبل الربط في التوجيه.
• ACF Options Pages بدون وسيطة language تتراجع إلى اللغة الافتراضية. مرّر language دائماً لاستعلامات صفحة الخيارات في المواقع متعددة اللغات.

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