Multi-language

This article helps collect all the resources you need to utilize 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 yours isn't on the list.

Translation workflow

Once you have your locales configured, you can create documents and translations, 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 locale(fr-fr). Here's an example of what 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:

LinkResolver.js

Copy

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

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

    default:
      return '/'
  }
}

The Link Resolver generates the correct routes that we'll use to dynamically create 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.

In this example, we query the documents of the type Page. It will determine the language of the documents by the $lang: String variable in the query:

page.js

Copy

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:

Query documents by Language

Retrieve the alternate_languages

Create a language switcher

Now that you've built dynamic localized pages and routes, 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.

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

Get the current and alternate languages

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

Please 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.

LangSwitcher.js

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>
  )
}

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 to see how it looks all put together.

Multi-languageMulti-language website example

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

Preview

Explore

Was this article helpful?

Not really

Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.