Comment interroger le contenu multilingue avec WPGraphQL – Filtrage des langues 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 traité sur 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 paramètre 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. Les articles et les termes traduits sont ce 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 front-end.

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é par WPML partout (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 aucun argument supplémentaire.

Récupérer chaque traduction 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 les 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 ainsi qu’un tableau de ses slugs et URI dans les 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 le front-end.

Menus multilingues

Interrogez les Menus et les éléments de menu par langue avec le même argument language :

query NavES {
  menu(language: "es", id: "primary", idType: SLUG) {
    menuItems {
      nodes {
        label
        url
        path
      }
    }
  }
}

Les label et 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 se résolvent automatiquement vers l’URI traduite. Cette prise en charge a été ajoutée dans WPML GraphQL 1.1.0.

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

Pour un sélecteur de langue global (indépendant de tout article unique), 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 de langue 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 les articles et les types de publication personnalisés suivent automatiquement la langue de l’article hôte. 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.

Limitations et solutions de contournement connues

• Les métadonnées d’auteur et d’utilisateur ne renvoient pas de valeurs traduites. Si vous affichez les biographies des auteurs par langue, stockez la biographie traduite dans un champ ACF sur l’utilisateur et interrogez ce champ à la place.
• URI traduites 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ée 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 l’intégrer au routage.
• Les pages d'Options ACF sans l’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 le côté WPML de la pile WPGraphQL 24 h/24 et 7 j/7.