Skip Navigation

Home » WPML Documentation » Related Projects » WPML GraphQL – Add Multilingual Functionality to the WPGraphQL Schema

WPML GraphQL – Add Multilingual Functionality to the WPGraphQL Schema

WPML GraphQL extends the capabilities of the WPGraphQL plugin, making it the ideal solution for developers looking to create multilingual websites using front-end technologies. Experience the ease of querying and filtering content and retrieving language-specific data and translations directly from the WPGraphQL schema.

Key Features

Extend WPGraphQL with additional fields (language, language code, translations) to retrieve specific data from the WPML plugin

Filter content within the Gatsby GraphQL schema

Filter posts, taxonomies, and comments by language

Retrieve language data for objects and nodes

Query data based on all installed languages or specific languages

Works with ACF, ACFML, and WPGraphQL for Advanced Custom Fields

On This Page:

Required Plugins and Setup

To get started, install and activate the following plugins:

If you are running a site with ACF or ACF Pro and want to expose multilingual fields from the ACF plugin to the WPGraphQL schema, install and activate:

Exploring the WPML GraphQL Schema

WPML GraphQL integrates with WPGraphQL and adds new fields and filters to the WPGraphQL schema. 

Once you install the plugins, you can go to GraphQL → GraphQL IDE and use the Query Composer to easily query and filter content in different languages. This includes:

  • Getting information about the language of queried objects
  • Getting translations for objects like post types, taxonomies, and comments.
  • Filtering the queried objects by language

As an example, the image below shows how you can retrieve a list of all posts on a WordPress site, including their language code, slug, and URI, as well as similar information for any translations of each post.

Using the language fields in the Query Composer to retrieve posts in all languages

To demonstrate how WPML GraphQL works, we set up a site with English set as the default language, and Spanish and Italian as the secondary languages. Throughout this documentation page, we use this test site to query posts and the post translations created by WPML.

Querying Language and Translation Information

WPML GraphQL lets you include language and translations fields in your query. This allows you to work with nodes and elements in GraphQL to retrieve language-specific data and associated translations.

  • You can add the language field to queries to indicate the language of post types, taxonomies, and comments. This query provides extensive language information, such as:
    • The language code
    • Country flag URLs
    • The native name of the language
    • The translated name of the language
    • The homepage URL
  • You can use the languageCode field to gather the language code for posts, taxonomy terms, and comments, without requesting any other language-specific details.
  • You can use the translations field to retrieve translations of post types and taxonomy terms.

Below, you can see an example of a query for posts that includes these fields.

WPML GraphQL query for posts using the language and translations fields 
query Posts{
  posts(where: {language: "en"}) {
    nodes {
      slug
      uri
      language {
        code
      }
      translations {
        slug
        uri
        language {
          code
        }
      }
    }
  }
}

Running this query returns language and translation information for each resource.

WPML GraphQL outcome of the query for posts using the language and translations fields 
{
  "data": {
    "posts": {
      "nodes": [
        {
          "slug": "bye-world",
          "uri": "/bye-world/",
          "language": {
            "code": "en"
          },
          "translations": [
            {
              "slug": "adios-mundo",
              "uri": "/es/adios-mundo/",
              "language": {
                "code": "es"
              }
            },
            {
              "slug": "addio-mondo",
              "uri": "/it/addio-mondo/",
              "language": {
                "code": "it"
              }
            }
          ]
        },
        {
          "slug": "hello-world",
          "uri": "/hello-world/",
          "language": {
            "code": "en"
          },
          "translations": [
            {
              "slug": "hola-mundo",
              "uri": "/es/hola-mundo/",
              "language": {
                "code": "es"
              }
            },
            {
              "slug": "ciao-mondo",
              "uri": "/it/ciao-mondo/",
              "language": {
                "code": "it"
              }
            }
          ]
        }
      ]
    }
  }
}

Language Filtering

The WPML GraphQL plugin comes equipped with a language filter, which lets you refine your queries to get the exact language data you’re interested in. 

You can use the language filter to filter posts, taxonomy terms, or comments based on a specific language. You can request nodes of a given language by including the language filter in your query, and you can also retrieve all items, regardless of language, by using the language filter with the value set to all.

Here’s an example query that filters posts by our secondary language, Spanish:

WPML GraphQL query using the language filter 
query PostsES{
  posts(where: {language: "es"}) {
    nodes {
      slug
      uri
    }
  }
}

As you can see, this query fetches all posts in Spanish.

WPML GraphQL outcome of the query using the language filter 
{
  "data": {
    "posts": {
      "nodes": [
        {
          "slug": "adois-mundo",
          "uri": "/es/adios-mundo/"
        },
        {
          "slug": "hola-mundo",
          "uri": "/es/hola-mundo/"
        }
      ]
    }
  }
}

Querying Data from Installed Languages 

WPML GraphQL defines two queries which let you query data from the languages installed on your site:

  • A languages query to get all registered languages, along with relevant data for each of them.
  • A defaultLanguage query to get the language set as the default language, along with its relevant data.

This may be useful if you want to, for example, build a language switcher.

Let’s say we want to query data for all installed languages. For this purpose, we run the following query:

WPML GraphQL query to get all registered languages 
query Languages {
  languages {
    code
    country_flag_url
    default_locale
    native_name
    translated_name
    url
  }
}

The query above produces the following outcome:

WPML GraphQL outcome of the query to get all registered languages 
{
  "data": {
    "languages": [
      {
        "code": "en",
        "country_flag_url": "http://site.com/wp-content/plugins/sitepress-multilingual-cms-release/res/flags/en.svg",
        "default_locale": "en_US",
        "native_name": "English",
        "translated_name": "English",
        "url": "http://site.com"
      },
      {
        "code": "es",
        "country_flag_url": "http://site.com/wp-content/plugins/sitepress-multilingual-cms-release/res/flags/es.svg",
        "default_locale": "es_ES",
        "native_name": "Español",
        "translated_name": "Spanish",
        "url": "http://site.com/es/"
      },
      {
        "code": "it",
        "country_flag_url": "http://site.com/wp-content/plugins/sitepress-multilingual-cms-release/res/flags/it.svg",
        "default_locale": "it_IT",
        "native_name": "Italiano",
        "translated_name": "Italian",
        "url": "http://site.com/it/"
      }
    ]
  }
}

Using WPML GraphQL with Gatsby and ACF

The Gatsby framework allows you to gather data from different backend sources, including WordPress sites.

If your WordPress site is using WP GraphQL, you can serve its data to a Gatsby site. With WPML GraphQL installed, you can serve data in different languages and even retrieve language information.

To provide additional functionality, WP GraphQL has an add-on for Advanced Custom Fields (ACF). By using this add-on along with the ACF Multilingual plugin from WPML, you can serve both core data and custom field data based on specific language requirements.

Let’s consider an example scenario: You have a Gatsby installation with the gatsby-source-graphql add-on package, which retrieves data from a WordPress backend. In this WordPress backend:

  1. You have WPML installed with Spanish set as the secondary language.
  2. You have ACF installed and added a field group (slug postfields) that includes a text field (slug subtitle) for posts. 
  3. You have populated some data.

With a simple GraphQL query, you can gather this data.

In the example query below, we retrieve posts from the WordPress backend where the language is set to English. For each post, we can access its title, language code, and ACF field data, such as the subtitle. Additionally, we can retrieve translations of the post, including their titles, language codes, and ACF field data.

WPML GraphQL example query for language-specific information and ACF field data 
export const doQuery = graphql`
  {
    wordpress {
      posts(where: {language: "en"}) {
        nodes {
          title
          language {
            code
          }
          postfields{
            subtitle
          }
          translations {
            title
            language {
              code
            }
            postfields{
              subtitle
            }
          }
        }
      }
    }
  }
`;

Known Issues

WPML works fine with this plugin, but sometimes there could be minor issues we're working on. This is expected as both plugins provide frequent updates.

Current unresolved issues:

You can also search all known issues including previously resolved issues for this plugin.

Getting Support

If you need help using WPML GraphQL with WPGraphQL, please head over to our support forum.

WPML Documentation
Kathy Banach
Updated
September 26, 2023