Multilingual Content

This article helps collect all the resources you need to take advantage of Prismic's multi-language and localization feature when building a Gatsby website.


1. Add locales to your repository

Go to your Dashboard, select your Prismic repository. Then go to Settings > Translations and Locales, and add all the languages you need.

Prismic offers a robust library of locale codes, but you can create a custom locale if the one you need isn't on the list.

Translation workflow

Once you have your locales configured, you can create documents and translations, manage the locales and locales, navigate the locales, copy the content, and more.

2. Create localized page routes

Create a Link Resolver to generate the localized routes for your site and declare it in your gatsby plugin configuration.

In this example, we have a repository with two locales. English (en-us) which is the master locale, and French (fr-fr). Here's an example of how we want the URLs to look like:

  • Home type: /en-us & /fr-fr
  • Page type: /en-us/about-us & /fr-fr/a-propos-de-nous

This would be the Link Resolver that generates localized routes. For the Home Custom Type we use lang as the language code and for the Page type and the lang and the uid of the document:

Copy
// Example LinkResolver.js file

exports.linkResolver = (doc) => {
  switch (doc.type) {
    case 'home': {
      return `/${doc.lang}`
    }

    case 'page': {
      return `/${doc.lang}/${doc.uid}`
    }

    default:
      return '/'
  }
}

The Link Resolver will generate the correct routes that we'll use to dynamically generate pages with Gatsby Node APIs or with the File System Route API.

3. Query by language

Once you have set up your dynamic routes and created all of your documents and translations in your repository, you'll need to query the documents by language. You'll use the lang value to query the documents by language.

Here's an example of a page.js template. We query the documents of the type Page. The language of the documents will be determined by the $lang: String variable in the query:

Copy
// Example page.js file

import * as React from 'react'
import { graphql } from 'gatsby'

const Page = ({ data }) => {
  if (!data) return null
  const pageContent = data.prismicPage

  return (
    <div>
      <h1>{pageContent.data.title.text}</h1>
    </div>
  )
}

export const query = graphql`
  query pageQuery($id: String, $lang: String) {
    prismicPage(id: { eq: $id }, lang: { eq: $lang }) {
      lang
      alternate_languages {
        id
        type
        lang
        uid
      }
      data {
        title {
          text
        }
      }
    }
  }
`

export default Page

Learn more about querying using metadata values:

Create a language switcher

Now that your dynamic localized pages and routes are built, you need to create a navigation button so users can select to switch between languages on your website. This can be anything from a <select> element if you have many languages, a button, or a boolean toggle switch if you only have two.

In this example, we'll show you how to build a selection component that lists the current and alternative languages.

Get the current and alternate languages

The first step is to get the current lang and the alternate_languages from the query to then pass it to the language switcher.

Take a look at our example. After retrieving these values from the query, we pass them as props to a LanguageSwitcher component that we'll create in the next step.

Copy
import * as React from 'react'
import { graphql } from 'gatsby'
import { LanguageSwitcher } from '../components/LanguageSwitcher'

const Page = ({ data }) => {
  if (!data) return null
  const pageContent = data.prismicPage

  return (
    <div>
      <h1>{pageContent.data.title.text}</h1>
      <LanguageSwitcher
        lang={pageContent.lang}
        altLangs={pageContent.alternate_languages}
      />
    </div>
  )
}

export const query = graphql`
  query pageQuery($id: String, $lang: String) {
    prismicPage(id: { eq: $id }, lang: { eq: $lang }) {
      lang
      alternate_languages {
        id
        type
        lang
        uid
      }
      data {
        title {
          text
        }
      }
    }
  }
`

export default Page

Create a language switcher component

In the 〜/src/components folder create a LangSwitcher.js file. Get the lang and altLangs values that we previously passed as props. We'll use Gatsby's navigate function to resolve the navigation of the links between routers in the <select> element, and the Link Resolver to direct to the correct URL.

Copy
import * as React from 'react'
import { navigate } from 'gatsby'

import { linkResolver } from '../utils/linkResolver'

export const LanguageSwitcher = ({ lang, altLang }) => {

 // Render the current language
  const currentLangOption = (
    <option value={lang}>{lang.slice(0, 2).toUpperCase()}</option>
  )

 // Render all the alternate language options
  const alternateLangOptions = altLang.map(
    (altLang, index) => (
      <option value={linkResolver(altLang)} key={`alt-lang-${index}`}>
        {altLang.lang.slice(0, 2).toUpperCase()}
      </option>
    ),
  )


 // Trigger select change event
  const handleLangChange = (event) => {
    navigate(event.target.value)
  }

  return (
    <li className="language-switcher">
      <select value={lang} onChange={handleLangChange}>
        {currentLangOption}
        {alternateLangOptions}
      </select>
    </li>
  )
}

Now you'll have a selection component that lists all the available locales in your repository so your visitors can quickly switch between locales.

Full example project

Take a look at this multi language example so you can see how it looks all put together.

Multi-languageMulti-language website example

Want to see a full, working project in action? Here you'll find an example multi-language website using Gatsby.js and Prismic.


Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.