Query by language

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

If you are taking advantage of the multi-language feature in your Prismic repository, then you'll need to be able to query documents for a specific language.

Query documents in all languages

By default, the Prismic GraphQL API will return documents in all the languages configured in your repository. You do not need to add anything to your query to retrieve all the languages:

Copy
{
  prismic {
    allPages {
      edges {
        node {
          text
          _meta {
            lang
          }
        }
      }
    }
  }
}

Query documents of a certain language

If you only want to retrieve documents for a particular language, simply add the lang argument and set it to the language code you want.

This is an example of how to retrieve all the documents of the type Page in traditional French ("fr-fr"). Then we retrieve a Title field that has the API ID of "text" and the meta data with the language code:

Copy
{
  prismic {
    allPages(lang: "fr-fr") {
      edges {
        node {
          text
          _meta {
            lang
          }
        }
      }
    }
  }
}


How to dynamically query documents by language

It is common that you will need to dynamically load documents in your Gatsby website using variables. This source plugin will help you dynamically create pages using the multi-language feature.

The plugin configuration

The plugin lives in the gatsby-config.js file of your project. Here's an example for Homepage, About, and Article pages (note that the configuration below excludes other options to focus only on the parts required for this example):

Copy
...
{
  resolve: "@prismicio/gatsby-source-prismic-graphql",
  options: {
    repositoryName: "your-repo-name",
    defaultLang: "en-us",
    langs: ["en-us", "fr-fr", "es-mx"],
    shortenUrlLangs: false,
    ...
    pages: [
      {
        type: "Homepage",
        match: "/:lang",
        component: require.resolve("./src/templates/homepage.js"),
      },
			{
        type: "About",
        match: "/:lang/:uid/",
        component: require.resolve("./src/templates/about.js"),
      },
      {
        type: "Article",
        match: "/article/:uid",
        component: require.resolve("./src/templates/article.js"),
        langs: ["fr-fr", "es-mx"],
      },
      {
        type: "News",
        match: "/news/:uid",
        component: require.resolve("./src/templates/article.js"),
        langs: ["fr-fr", "es-mx"],
      },
    ],
  },
},

The following five properties will help you achieve the multi-language configuration:

  • options.defaultLang - The master language in your Prismic repository
  • options.langs - An array of all available languages in your Prismic repository
  • options.pages.langs - Languages that you want to make available for each template. Note that you'll only need to add this if you want to overwrite the top level lang config (options.langs). For more about this, read the 'How to exclude languages from a route' section further down in this article.
  • options.shortenUrlLangs - If you set this value to true, you'll slice the default language code to create a shorter URL. So if your route was /en-us you can change it to be just /en. Note that because there are many language codes that begin with the same slug (e.g. 'en-us' and 'en-gb'), you'll need to add another parameter that makes the url unique, for example: the UID of a document.
  • options.pages.match - The dynamic routes that are going to be generated for each page type

Querying documents in multiple languages

Homepage example

Using the configuration defined above, the Homepage documents are defined with the following route options.pages.match: "/:lang". The generated URLs for the homepages will look like this:

  • US English: /en-us
  • French: /fr-fr
  • MX Spanish: /es-mx

Here's what the query would look like in the src/templates/homepage.js file:

Copy
query myHomepages($lang: String) {
  prismic {
    allHomepages(lang: $lang) {
      edges {
        node {
          _meta {
            lang
          }
        }
      }
    }
  }
}

Example query

Using the configuration defined above, the About documents are defined with the following route options.pages.match: "/:lang/:uid". The generated URLs for the homepages will look like this:

  • US English: /en-us/about-us
  • French: /fr-fr/a-propos-de-nous
  • MX Spanish: /es-mx/acerca-de-nosotros

Here's what the query would look like in the src/templates/about.js file:

Copy
query AboutPages($uid: String, $lang: String) {
  prismic {
    allAbouts(uid: $uid, lang: $lang) {
      edges {
        node {
          _meta {
            lang
            uid
          }
        }
      }
    }
  }
}

How to exclude languages from a route

You can exclude one or more languages of the retrieved documents. If you add options.pages.langs (which will only have the languages that you indicate) this will overwrite options.langs (which holds all the available languages in your repository). This configuration will allow you to exclude as many languages as you need.

Here's an example of the plugin configuration for Articles. We are excluding the English ("en-us") language so pages are only going to be generated for French ("fr-fr") and Spanish ("es-mx"). (note that the configuration below excludes other options to focus only on the parts required for this example):

Copy
{
  resolve: "@prismicio/gatsby-source-prismic-graphql",
  options: {
    ...
    defaultLang: "en-us",
    langs: ["en-us", "fr-fr", "es-mx"],
    ...
    pages: [
      {
        type: "Articles",
        match: "/:lang",
        component: require.resolve("./src/templates/homepage.js"),
        langs: ["fr-fr", "es-mx"],
      },
    ],
  },
},

Exclude the language code from the default language route

To learn how to do this, let's use the Homepage example above. If you'd like to exclude the language code from the main language page to have the slug to be just / instead of /en-us. You need to add two things:

  1. The options.defaultLang
  2. A question mark ? after the :lang portion of the options.pages.match property.

Here's the example of the plugin configuration for the Homepages (note that the configuration below excludes other options to focus only on the parts required for this example):

Copy
{
  resolve: "gatsby-source-prismic-graphql",
  options: {
    ...
    defaultLang: "en-us",
    langs: ["en-us", "fr-fr", "es-mx"],
    ...
    pages: [
      {
        type: "Homepage",
        match: "/:lang?",
        component: require.resolve("./src/templates/homepage.js"),
      },
    ],
  },
},

These are going to be the generated URL slugs:

  • US English: /
  • French: /fr-fr
  • MX Spanish: /es-mx