כיצד לבצע שאילתות על תוכן רב-לשוני באמצעות 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 להלן מסננות ומחזירות.

סביבת הפיתוח (IDE) של GraphQL – היכן לבדוק שאילתות

WPGraphQL מוסיף מסך GraphQL ← GraphQL IDE לאזור הניהול של WordPress. מרכיב השאילתות (Query Composer) של סביבת הפיתוח מפרט כל שדה זמין, כולל הארגומנט language והשדה translations של WPML, ומריץ שאילתות מול האתר הפעיל שלך. בדוק שאילתות שם לפני חיבורן לתשתית צד הלקוח שלך.

נקודת הקצה (Endpoint) של 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 }
      }
    }
  }
}

כאשר צומת (node) ברמה העליונה מסונן לפי שפה, פריטים מקושרים (קטגוריות, תגיות, טקסונומיות מותאמות אישית) עוקבים אוטומטית אחר אותה שפה. השאילתה לעיל מחזירה פוסטים בספרדית עם קטגוריות בספרדית, ללא צורך בארגומנטים נוספים.

שליפת כל תרגום של צומת בשאילתה אחת

הוסף את השדה translations לכל שאילתת פוסט או טקסונומיה כדי להחזיר את הגרסאות בשפות האחרות של הצומת באותו מטען נתונים (payload):

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

כל פוסט חוזר עם השדות שלו באנגלית, בתוספת מערך של מזהי הכתובות (slugs) וכתובות ה־URI שלו בשפות האחרות. זוהי התבנית שבה משתמש בורר שפות המוצג לצד תוכן העמוד: בקשה אחת, כל החלופות שאליהן המבקר יכול לעבור.

שאילתה לפוסט ספציפי לפי מזהה (ID) או מזהה כתובת (slug) בכל שפה

כדי לשלוף פוסט מתורגם יחיד ישירות (לפי מזהה הכתובת המתורגם שלו או לפי מזהה מסד הנתונים), השתמש בשאילתת 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 של דף הבית של השפה. אלו מספיק נתונים כדי להציג בורר של דגל ותווית ללא קידוד קשיח (hard-coding) של רשימת השפות.

שאילתת שדות מותאמים אישית של ACF לפי שפה

כאשר ACFML ו־WPGraphQL for ACF פעילים, שדות 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. באפשרות תרגום מאפייני משתמש, בחר את תפקידי המשתמשים ושמור.
3. תרגם את המחרוזות בדומיין Authors.

תקלות ידועות ופתרונות עוקפים

• כתובות URI מתורגמות בתבניות שאילתה מסוימות. בעת שליפת פוסט מתורגם לפי URI (contentNode(id: "/de/some-slug/", idType: URI)), ודא שכתובת ה־URI המוחזרת תואמת למה שפורסם בשפה – תבניות שאילתה מסוימות מחזירות נתיבים לא עקביים. בדוק ב־GraphQL IDE לפני החיבור לניתוב (routing).
• עמודי אפשרויות של ACF ללא הארגומנט language חוזרים לשפת ברירת המחדל. הוסף תמיד את language עבור שאילתות עמוד אפשרויות באתרים רב-לשוניים.

אם נתקלת בבעיית שילוב שאינה מופיעה כאן, צוות התמיכה של WPML מספק מענה לצד של WPML במערך WPGraphQL 24/7.