Gatsby 5 is here and Slices are a big part of what makes it great. Today, we’ll walk through creating an internationalized site with Slices.
Heads up! If you’re not sure what I’m talking about, you can introduce yourself to Slices with this blog post or this YouTube video. The rest of the post will assume you get the concept of slices.
Why use Slices alongside internationalization (i18n)? The Slice API allows you to make a Slice component for each language, and swap which Slice component is used on each page based on the language. Without Slices, a change to the header component or text within the header would require a rebuild of every page that contains that component. Using the Slice API, the three header Slice components created (one for English, German, and Japanese) will be built separately and be stitched in, making the build way faster.
Let’s take a look at the project we’ll be modifying and the way this will work.
The Project
The final build here contains 6 pages in total– 2 pages per language (we chose 3– German, Japanese, and English), with 3 header Slice components (one for each language). In this example, we’re only translating the header. We want to create a Slice component for each language and then tell Gatsby which Slice component to use on each page. This avoids updating every page when a translated text changes (or we change the code for the header component).
The project has a home and bio page, and the route will specify the language: /en/bio will take you to the bio page with an English header, and /jp will take you to the home page with a Japanese header.
You can see the demo running on Gatsby Cloud, and the finished code on GitHub.
Let’s start implementing!
Writing the Code
First, I translated the text in the header component for each language. We’ll populate this information, both the supported languages and the translations, into our GraphQL layer using createNode() in gatsby-node.js (Note: you can use data from anywhere, like an API or a CMS, we’re just hard coding for this demo):
We’ll create a Slice component for each language within the createPages API using the existing header component. In the gatsby-node.js file, we’ll add the following:
In this code, we create 3 Slice components with the ids header-en, header-jp, and header-de. When each of these Slices are rendered, they will use the header.js component as the root component. Similar to createPage’s context, we’re also passing a context to the Slice, which can be used in the component’s GraphQL query or the component itself through the prop sliceContext.
Inside the SUPPORTED_LANGUAGES.forEach(), we’ll add the code to create our pages:
Now that we’ve created our Slice Components, created our Pages, and given each page our desired Slice Components, we just have to render the Slice. In layout.js, we call our Slice placeholder:
Now we’ll have a page created for each language, and anywhere the header Slice alias is seen, the correctly-translated header Slice will be “stitched” into the page.
One neat thing about Slices is that they actually support GraphQL queries, just like pages. Using the context passed to the slice through createSlice, we can know which language we’re rendering. We’ll use this context as GraphQL variables to query for all of the translated text we need for this header.
Note that we use the language passed into the Header component to set the links and pull only the translations we need from GraphQL.
That’s it! We can now build our site in the terminal with npm run develop. You should see a website at localhost:8000 that allows you to view the project in all three languages, all six pages.
What Next?
Using the Slice API makes warm builds faster on nearly all Gatsby sites– if you have a component you dread changing for fear of slow builds of all your pages, it’s time to upgrade to Gatsby 5 and give Slices a try. If you’d like to learn more, there’s documentation on Slices. You can also learn more about all the new features in Gatsby 5 on our swanky new landing page and our recent blog post.