Mehrsprachige Inhalte mit WPGraphQL abfragen – Sprachfilterung und Übersetzungen

Bevor Sie beginnen

Installieren und aktivieren Sie diese Plugins:

• WPGraphQL (das Open-Source-Plugin des WPGraphQL-Projekts).
• WPML und die WPML String-Übersetzung.
• WPML GraphQL (das Add-on, das auf dieser Seite behandelt wird).

Wenn Sie auch Advanced Custom Fields verwenden:

• Advanced Custom Fields Multilingual (ACFML).
• WPGraphQL for Advanced Custom Fields (vom WPGraphQL-Projekt).

Ihre Ausgangsinhalte müssen in WPML übersetzt werden, bevor die unten stehenden Abfragen etwas zurückgeben können. Wenn Alles automatisch übersetzen aktiviert ist (der Standard in WPML 5), werden Übersetzungen im Hintergrund erstellt, während Sie Inhalte veröffentlichen. Für eine manuelle Einrichtung senden Sie Inhalte aus dem WPML → Übersetzungs- → Dashboard zur Übersetzung. Die übersetzten Beiträge und Begriffe sind das, was die unten stehenden GraphQL-Abfragen filtern und zurückgeben.

Die GraphQL-IDE – Wo Sie Abfragen testen können

WPGraphQL fügt dem WordPress-Admin-Bereich einen GraphQL → GraphQL IDE-Bildschirm hinzu. Der Query Composer der IDE listet jedes verfügbare Feld auf, einschließlich des language-Arguments und des translations-Felds von WPML, und führt Abfragen gegen Ihre Live-Website aus. Testen Sie Abfragen dort, bevor Sie sie in Ihr Frontend-Framework integrieren.

Der GraphQL-Endpunkt für jede Sprache

WPGraphQL antwortet unter /graphql. Eine Abfrage ohne ein language-Argument gibt Inhalte in Ihrer Standardsprache zurück. Um Inhalte in einer anderen Sprache zu erhalten, fügen Sie der Abfrage where: { language: "es" } hinzu.

Inhalte nach Sprache abfragen

Fügen Sie where: { language: "<code>" } zu jeder Listenabfrage hinzu: Beiträge, benutzerdefinierte Beitragstypen, Taxonomie-Begriffe, Menüs, Menüpunkte, Kommentare. Der Sprachcode ist derselbe Code, den WPML überall verwendet (en, es, fr, pt-pt usw.). Übergeben Sie language: "all", um Inhalte aus allen Sprachen gleichzeitig zurückzugeben.

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

Wenn ein Knoten auf oberster Ebene nach Sprache gefiltert wird, folgen verbundene Elemente (Kategorien, Schlagwörter, benutzerdefinierte Taxonomien) automatisch derselben Sprache. Die obige Abfrage gibt Beiträge auf Spanisch mit Kategorien auf Spanisch zurück, ohne dass zusätzliche Argumente erforderlich sind.

Jede Übersetzung eines Knotens in einer Abfrage abrufen

Fügen Sie das Feld translations zu einer beliebigen Beitrags- oder Taxonomie-Abfrage hinzu, um die fremdsprachigen Versionen des Knotens im selben Payload zurückzugeben:

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

Jeder Beitrag wird mit seinen englischen Feldern sowie einem Array seiner fremdsprachigen Slugs und URIs zurückgegeben. Das ist die Struktur, die ein Sprachumschalter verwendet, der neben dem Seiteninhalt gerendert wird: eine Anfrage, jede Alternative, zu der der Besucher wechseln kann.

Einen bestimmten Beitrag nach ID oder Slug in einer beliebigen Sprache abfragen

Um einen einzelnen übersetzten Beitrag direkt abzurufen (über seinen übersetzten Slug oder die Datenbank-ID), verwenden Sie die singuläre post-Abfrage mit 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 }
  }
}

Beide Abfragen geben den übersetzten Beitrag (Titel, Slug, URI) zurück, ohne dass eine weitere Filterung im Frontend erforderlich ist.

Mehrsprachige Menüs

Fragen Sie Menüs und Menüpunkte pro Sprache mit demselben where: { language }-Argument ab. Um die Elemente einer Theme-Menüposition zu erhalten, fügen Sie auch die Position hinzu:

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

Um die Menüs einer Sprache aufzulisten, verwenden Sie die menus-Abfrage:

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

label und url jedes Menüpunkts werden in der abgefragten Sprache zurückgegeben. Menüpunkte, die auf übersetzte Beiträge verlinken, werden automatisch zur übersetzten URI aufgelöst. Die singuläre menu-Abfrage hat kein language-Argument, verwenden Sie also menus oder menuItems, um die Sprache auszuwählen.

Installierte Sprachen – Für einen Sprachumschalter

Für einen globalen Sprachumschalter (unabhängig von einem einzelnen Beitrag) verwenden Sie die Abfragen languages und defaultLanguage, um jede Sprache auf der Website aufzulisten:

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

Gibt einen Knoten pro aktiver Sprache mit der Flaggen-URL, dem muttersprachlichen Namen, dem übersetzten Namen und der Startseiten-URL der Sprache zurück. Das sind genug Daten, um einen Sprachumschalter mit Flagge und Beschriftung zu rendern, ohne die Sprachliste hartkodieren zu müssen.

Benutzerdefinierte Felder von ACF nach Sprache abfragen

Wenn ACFML und WPGraphQL for ACF aktiv sind, geben ACF-Felder in einem Beitrag oder benutzerdefinierten Beitragstyp die in diesem Beitrag gespeicherten Werte zurück. Jede Übersetzung hat ihre eigenen Werte, fragen Sie also den Beitrag in der Sprache ab, die Sie benötigen. Es ist kein zusätzliches Argument erforderlich.

Für ACF-Optionsseiten, die nicht an einen einzelnen Beitrag gebunden sind, fügen Sie der Optionsseiten-Abfrage das language-Argument hinzu:

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

Das Argument erwartet einen Sprachcode, der einer der aktiven Sprachen Ihrer Website entspricht.

Seit WPGraphQL for ACF 3.0.0 ist eine Optionsseite nur dann im GraphQL-Schema enthalten, wenn Sie show_in_graphql dafür aktivieren. Ohne diese Einstellung existieren die Optionsseiten-Abfrage und ihr language-Argument nicht. Wenn Sie die Optionsseite im Code registrieren, fügen Sie die Einstellung dort hinzu:

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

Übersetzte Autorendetails

WPML GraphQL gibt die übersetzten firstName, lastName, nickname und description von Benutzern zurück. Um sie zu übersetzen:

1. Gehen Sie zur Seite WPML → String-Übersetzung.
2. Wählen Sie in der Option Benutzereigenschaften übersetzen die Benutzerrollen aus und speichern Sie.
3. Übersetzen Sie die Strings in der Domain Authors.

Bekannte Einschränkungen und Problemumgehungen

• Übersetzte URIs in einigen Abfragestrukturen. Wenn Sie einen übersetzten Beitrag über die URI (contentNode(id: "/de/some-slug/", idType: URI)) abrufen, überprüfen Sie, ob die zurückgegebene URI mit dem übereinstimmt, was in der jeweiligen Sprache veröffentlicht ist – einige Abfragestrukturen geben inkonsistente Pfade zurück. Testen Sie dies in der GraphQL-IDE, bevor Sie es in Ihr Routing integrieren.
• ACF-Optionsseiten ohne language-Argument fallen auf die Standardsprache zurück. Übergeben Sie bei Abfragen von Optionsseiten auf mehrsprachigen Websites immer language.

Wenn Sie auf ein hier nicht aufgeführtes Integrationsproblem stoßen, steht Ihnen das WPML-Support-Team für die WPML-Seite des WPGraphQL-Stacks 24/7 zur Verfügung.