Comment interroger du contenu multilingue avec WPGraphQL – Filtrage par langue et traductions

Avant de commencer

Installez et activez ces extensions :

• WPGraphQL (l’extension open source du projet WPGraphQL).
• WPML et WPML Traduction de chaînes.
• WPML GraphQL (le module complémentaire couvert par cette page).

Si vous utilisez également Advanced Custom Fields :

• Advanced Custom Fields Multilingual (ACFML).
• WPGraphQL for Advanced Custom Fields (du projet WPGraphQL).

Votre contenu source doit être traduit dans WPML avant que les requêtes ci-dessous n’aient quoi que ce soit à renvoyer. Si l’option Tout traduire automatiquement est activée (le réglage par défaut de WPML 5), les traductions sont produites en arrière-plan à mesure que vous publiez du contenu. Pour une configuration manuelle, envoyez le contenu à traduire depuis WPML → Traductions → Tableau de bord. Ce sont les articles et termes traduits que les requêtes GraphQL ci-dessous filtrent et renvoient.

L’IDE GraphQL – Où tester les requêtes

WPGraphQL ajoute un écran GraphQL → GraphQL IDE à l’interface d'administration de WordPress. Le Query Composer de l’IDE répertorie tous les champs disponibles, y compris l’argument language et le champ translations de WPML, et exécute des requêtes sur votre site en production. Testez-y les requêtes avant de les intégrer à votre framework d’interface publique.

Le point de terminaison GraphQL pour chaque langue

WPGraphQL répond à l’adresse /graphql. Une requête sans argument language renvoie le contenu dans votre langue par défaut. Pour obtenir du contenu dans une autre langue, ajoutez where: { language: "es" } à la requête.

Interroger le contenu par langue

Ajoutez where: { language: "<code>" } à n’importe quelle requête de liste : articles, types de publication personnalisés, termes de taxonomie, menus, éléments de menu, commentaires. Le code de langue est le même que celui utilisé partout par WPML (en, es, fr, pt-pt, etc.). Transmettez language: "all" pour renvoyer le contenu de toutes les langues à la fois.

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

Lorsqu’un nœud de niveau supérieur est filtré par langue, les éléments connectés (catégories, étiquettes, taxonomies personnalisées) suivent automatiquement la même langue. La requête ci-dessus renvoie des articles en espagnol avec des catégories en espagnol, sans argument supplémentaire.

Récupérer toutes les traductions d’un nœud en une seule requête

Ajoutez le champ translations à n’importe quelle requête d’article ou de taxonomie pour renvoyer les versions dans d’autres langues du nœud dans la même charge utile :

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

Chaque article est renvoyé avec ses champs en anglais plus un tableau de ses slugs et URI dans d’autres langues. C’est la structure qu’utilise un sélecteur de langue affiché à côté du contenu de la page : une seule requête, toutes les alternatives vers lesquelles le visiteur peut basculer.

Interroger un article spécifique par ID ou slug dans n’importe quelle langue

Pour récupérer directement un seul article traduit (par son slug traduit ou par son ID de base de données), utilisez la requête singulière post avec 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 }
  }
}

Les deux requêtes renvoient l’article traduit (titre, slug, URI) sans filtrage supplémentaire sur l’interface publique.

Menus multilingues

Interrogez les menus et les éléments de menu par langue avec le même argument where: { language }. Pour obtenir les éléments d’un emplacement de menu du thème, ajoutez également l’emplacement :

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

Pour lister les menus d’une langue, utilisez la requête menus :

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

Le label et l’url de chaque élément de menu sont renvoyés dans la langue interrogée. Les éléments de menu qui renvoient vers des articles traduits sont automatiquement résolus vers l’URI traduit. La requête singulière menu n’a pas d’argument language, utilisez donc menus ou menuItems pour choisir la langue.

Langues installées – Pour un sélecteur de langue

Pour un sélecteur de langue global (indépendant de tout article), utilisez les requêtes languages et defaultLanguage pour lister toutes les langues du site :

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

Renvoie un nœud par langue active avec l’URL du drapeau, le nom natif, le nom traduit et l’URL d’accueil de la langue. Ce sont des données suffisantes pour afficher un sélecteur avec drapeau et libellé sans coder en dur la liste des langues.

Interroger les champs personnalisés ACF par langue

Lorsque ACFML et WPGraphQL for ACF sont actifs, les champs ACF sur un article ou un type de publication personnalisé renvoient les valeurs enregistrées sur cet article. Chaque traduction a ses propres valeurs, interrogez donc l’article dans la langue dont vous avez besoin. Aucun argument supplémentaire n’est nécessaire.

Pour les pages d’options ACF, qui ne sont pas liées à un seul article, ajoutez l’argument language à la requête de la page d’options :

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

L’argument attend un code de langue qui correspond à l’une des langues actives de votre site.

Depuis WPGraphQL for ACF 3.0.0, une page d’options n’est présente dans le schéma GraphQL que si vous activez show_in_graphql pour celle-ci. Sans cela, la requête de la page d’options et son argument language n’existent pas. Si vous enregistrez la page d’options dans le code, ajoutez-y le réglage :

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

Détails de l’auteur traduits

WPML GraphQL renvoie les éléments firstName, lastName, nickname et description traduits des utilisateurs. Pour les traduire :

1. Accédez à la page WPML → Traduction de chaînes.
2. Dans l’option Translate User properties, sélectionnez les rôles d’utilisateur et enregistrez.
3. Traduisez les chaînes de texte dans le domaine Authors.

Anomalies connues et solutions de contournement

• URI traduits dans certaines structures de requêtes. Lors de la récupération d’un article traduit par URI (contentNode(id: "/de/some-slug/", idType: URI)), vérifiez que l’URI renvoyé correspond à ce qui est publié dans la langue – certaines structures de requêtes renvoient des chemins incohérents. Testez dans l’IDE GraphQL avant de les intégrer au routage.
• Les pages d’options ACF sans argument language se rabattent sur la langue par défaut. Transmettez toujours language pour les requêtes de pages d’options sur les sites multilingues.

Si vous rencontrez un problème d’intégration qui n’est pas répertorié ici, l’équipe d’assistance de WPML couvre la partie WPML de la pile WPGraphQL 24 h/24 et 7 j/7.