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.
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.
Once you have your locales configured, you can create documents and translations, navigate the locales, copy the content, and more.
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:
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.
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:
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:
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.
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.
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
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.
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.
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.
Was this article helpful?
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.