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 lets you query, filter, and retrieve language-specific content and translations from the WPGraphQL schema.

Key Features

Filter content by language, including posts, taxonomies, comments, menus, and menu items

Extend WPGraphQL with language fields to retrieve specific data from the WPML plugin

Query data across all installed languages or focus on specific languages

On this page

Required Plugins

What Can You Do with WPML GraphQL?

Querying Language and Translation Information

Language Filtering

Querying Specific Posts Across Languages

Querying Data from Installed Languages

Using WPML GraphQL with Gatsby and ACF

Get Started with WPML GraphQL

Required Plugins

To get started, install and activate the following plugins:

  • WPGraphQL
  • WPML 
  • WPML String Translation
  • WPML GraphQL 

To include multilingual fields from the ACF plugin in the WPGraphQL schema, also install:

What Can You Do with WPML GraphQL?

WPML GraphQL integrates with WPGraphQL to allow you to query multilingual content created with WPML.

From GraphQL → GraphQL IDE, you can use the Query Composer to:

  • Get language information for any content you query
  • Access translations for posts, taxonomies, and comments
  • Filter your queries by language
  • Query specific posts across languages by their ID or slug

For example, as the image below shows, you can easily pull up a list of all posts on your site, complete with their language codes, slugs, URIs, and details for their translations.

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

Below, we’ll use a multilingual test site to show you how to use WPML GraphQL to query content and its translations.

Querying Language and Translation Information

With WPML GraphQL, you can use the language and translation fields in your queries:

  • The language field lets you retrieve details like the language code, country flag URL, native name, translated name, and homepage URL for post types, taxonomies, menus, menu items, and comments.
  • The languageCode field gets the language code for posts, taxonomy terms, menus, menu items, and comments without additional language details.
  • The translations field retrieves translations for post types and taxonomy terms.

When you query comments, the language and languageCode fields match the language of the post they belong to.

Here’s an example of a query that retrieves posts along with their associated details, including the post slug, URI, language code, categories, and any translations that exist:

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

Running this query returns language and translation information for each post, along with connected items like categories. The connections automatically follow the language of the top-level item (posts in this case):

{
  "data": {
    "posts": {
      "nodes": [
        {
          "slug": "bye-world",
          "uri": "/2023/05/18/bye-world/",
          "language": {
            "code": "en"
          },
          "categories": {
            "nodes": [
              {
                "name": "End of the day"
              },
              {
                "name": "Greetings"
              }
            ]
          },
          "translations": [
            {
              "slug": "adios-mundo",
              "uri": "/es/2023/05/18/adios-mundo/",
              "language": {
                "code": "es"
              },
              "categories": {
                "nodes": [
                  {
                    "name": "Fin del día"
                  },
                  {
                    "name": "Saludos"
                  }
                ]
              }
            },
            {
              "slug": "tchau-mundo",
              "uri": "/pt-pt/2023/05/18/tchau-mundo/",
              "language": {
                "code": "pt-pt"
              },
              "categories": {
                "nodes": [
                  {
                    "name": "Fim do dia"
                  },
                  {
                    "name": "Saudações"
                  }
                ]
              }
            }
          ]
        },
        {
          "slug": "hello-world",
          "uri": "/2018/07/05/hello-world/",
          "language": {
            "code": "en"
          },
          "categories": {
            "nodes": [
              {
                "name": "Greetings"
              },
              {
                "name": "Start of the day"
              }
            ]
          },
          "translations": [
            {
              "slug": "hola-mundo",
              "uri": "/es/2018/07/05/hola-mundo/",
              "language": {
                "code": "es"
              },
              "categories": {
                "nodes": [
                  {
                    "name": "Inicio del día"
                  },
                  {
                    "name": "Saludos"
                  }
                ]
              }
            },
            {
              "slug": "ola-mundo",
              "uri": "/pt-pt/2018/07/05/ola-mundo/",
              "language": {
                "code": "pt-pt"
              },
              "categories": {
                "nodes": [
                  {
                    "name": "Começo do dia"
                  },
                  {
                    "name": "Saudações"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}

Language Filtering

WPML GraphQL lets you use the language filter to:

  • Filter posts, taxonomy terms, menus, menu items, or comments by a specific language
  • Retrieve content in a particular language by setting the filter accordingly
  • Get all content, regardless of language, by setting the filter value to all

WPML GraphQL supports connections, so when you filter a top-level item like a post by language, all related items, such as categories and tags, will automatically follow the same language. This makes your queries consistent and accurate.

Here’s an example of a query that retrieves posts in Spanish, including their slugs, URIs, and connected categories:

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

Here’s what the query returns:

{
  "data": {
    "posts": {
      "nodes": [
        {
          "slug": "adios-mundo",
          "uri": "/es/2023/05/18/adios-mundo/",
          "categories": {
            "nodes": [
              {
                "name": "Fin del día"
              },
              {
                "name": "Saludos"
              }
            ]
          }
        },
        {
          "slug": "hola-mundo",
          "uri": "/es/2018/07/05/hola-mundo/",
          "categories": {
            "nodes": [
              {
                "name": "Inicio del día"
              },
              {
                "name": "Saludos"
              }
            ]
          }
        }
      ]
    }
  }
}

Querying Specific Posts Across Languages

With WPMLGraphQL, you can also query individual posts in any language by their post ID or slug.  

For example, if you have a post titled ¡Hola mundo! (the Spanish translation of Hello world!), with a slug of hola-mundo and a post ID of 2, you can use the following queries to retrieve the post:

query PostBySlug {
  post(id: "hola-mundo", idType: SLUG) {
    title
    slug
    uri
  }
}

query PostById {
  post(id: "2", idType: DATABASE_ID) {
    title
    slug
    uri
  }
}

Both queries will correctly return the post data, including the title, slug, and URI, for the ¡Hola mundo! post: 

{
  "data": {
    "post": {
      "title": "¡Hola mundo!",
      "slug": "hola-mundo",
      "uri": "/es/2018/07/05/hola-mundo/"
    }
  }
}

Querying Data from Installed Languages 

WPML GraphQL provides two queries for accessing data about the languages installed on your site:

  • The languages query retrieves all registered languages along with relevant data for each
  • The defaultLanguage query retrieves information about the default language set on your site

These queries can be helpful if you’re looking to build features like a language switcher.

For example, to get data for all installed languages, you can run the following query:

query Languages {
  languages {
    code
    country_flag_url
    default_locale
    native_name
    translated_name
    url
  }
}

The query above produces the following outcome:

{
  "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

Gatsby allows you to source data from WordPress, and with WPML GraphQL, you can serve multilingual content and language-specific data to your Gatsby site.

If you’re using WP GraphQL with the ACF plugin, WPML GraphQL and ACF Multilingual extend this functionality, enabling you to query custom field data in different languages.

For example, let’s say you have a Gatsby installation with the gatsby-source-graphql add-on package, and your WordPress site has WPML (with Spanish as a secondary language) and ACF installed.

You can retrieve multilingual posts with their titles, language codes, and custom ACF fields in Gatsby using a simple GraphQL query.

export const doQuery = graphql`
  {
    wordpress {
      posts(where: {language: "en"}) {
        nodes {
          title
          language {
            code
          }
          postfields{
            subtitle
          }
          translations {
            title
            language {
              code
            }
            postfields{
              subtitle
            }
          }
        }
      }
    }
  }
`;

Get Started with WPML GraphQL

To use WPML GraphQL, you need a WPML Multilingual CMS or WPML Multilingual Agency plan. Both plans provide access to the WPML plugin and a wide range of additional add-ons, all included at no extra charge.

See which plan is best for your site.

Need Help?

If you have trouble using WPML GraphQL, visit our Known Issues and Solutions page for troubleshooting tips.

Still need help? Submit a support ticket.

Kathy Banach
Updated
February 19, 2025