Rendering Alternate Languages

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.

Before you learn how to render the alternate languages of your documents, you will need to know how to retrieve the alternateLanguages array as shown in this article.

There are many different use cases for rendering this information, the most obvious being so you can switch language versions of a document which we will show in the example below. In this example we are going to get some simple data from a blog post document, but first there is some configuration to be done.

NOTE: The example below requires the Link Resolver, so you can learn about this function here, it also employs dynamic querying by UID.


First you will need to set the languages in the options section of the gatsby-source-prismic-graphql plugin. In the example below set the options.defaultLang parameter with the master language and options.langs parameter with all available languages from the repo.

Then we configure the options.pages.match parameter to help dynamically generate the URL of the document, you can learn more about this process here. Then in option.pages.langs we set any available languages for that custom type.

options: {
  repositoryName: 'your-repo-name',
  defaultLang: 'en-gb',
  langs: ['en-gb', 'fr-fr'],
  pages: [{
    type: 'Post',
    match: '/blog/:lang/:uid',
    path: '/blog-preview',
    component: require.resolve('./src/templates/post.js'),
    langs: ['en-gb', 'fr-fr'],

NOTE: The configuration above excludes other options to focus only on the ones required for this example. You can see a full list of options here.

Before we move on to our page template we need to define our page routes in our Link Resolver file. This will help link and redirect to the correct pages based off of the language and UID of the Prismic document.

export const linkResolver = doc => {
  // Route for blog posts
  if (doc.type === 'post') {
    return `/blog/${doc.lang}/${doc.uid}`

  // Homepage route fallback
  return '/';

Render the language switcher

Now let's take a look at a simple full page component example where we have a title and a link to change the document language. First we make sure we import the Link Resolver and the Link component from Gatsby to process the alternate language.

Also you can see here how we dynamically query a document by UID and by the language. We then render the title on the page and now we can finally use the alternate languages.

First we map the alternateLanguages and render links for each one of them by passing each altLang through the Link Resolver. Then we take the language code lang and create a label for the link.

import React from 'react'
import { graphql, Link } from 'gatsby'
import { RichText } from 'prismic-reactjs'
import { linkResolver } from 'gatsby-source-prismic-graphql'

// Query for the Blog Post content in Prismic
export const query = graphql`
query BlogPostQuery($uid: String, $lang: String) {
  prismic {
    allPosts(uid: $uid, lang: $lang){
      edges {
        node {
          _meta {
            alternateLanguages {

const Post = ({ data }) => {
  const document = data.prismic.allPosts.edges[0].node
  return (
        {/* map the alternateLanguages and render links for each one */}
          ?, index) => {
              return (
          : null}

export default Post

Which results in the language switcher below:

A working language switcher

There you have it! A simple of example of how to change a documents language with the alternateLanguages array and the Link Resolver.