Login
In Part 1 of this series, we peeked at how to add i18n to a Gatsby blog using a motley set of Gatsby plugins. They are great if you know what they can do, how to use them, and how they work. Still, plugins don’t always work great together since they are often written by different developers, which can introduce compatibility issues and cause an even bigger headache. Besides, we usually use plugins for more than i18n since we also want to add features like responsive images, Markdown support, themes, CMSs, and so on, which can lead to a whole compatibility nightmare if they aren’t properly supported.
How can we solve this? Well, when working with an incompatible, or even an old, plugin, the best solution often involves finding another plugin, hopefully one that provides better support for what is needed. Otherwise, you could find yourself editing the plugin’s original code to make it work (an indicator that you are in a bad place because it can introduce breaking changes), and unless you want to collaborate on the plugin’s codebase with the developers who wrote it, it likely won’t be a permanent solution.
But there is another option!
Note: Here is the Live Demo.
The Solution: Make Your Own Plugin!Sure, that might sound intimidating, but adding i18n from scratch to your blog is not so bad once you get down to it. Plus, you gain complete control over compatibility and how it is implemented. That’s exactly what we are going to do in this article, specifically by adding i18n to the starter site — a cooking blog — that we created together in Part 1.
The StarterYou can go ahead and see how we made our cooking blog starter in Part 1 or get it from GitHub.
This starter includes a homepage, blog post pages created from Markdown files, and blog posts authored in English and Spanish.
What we will do is add the following things to the site:
Let’s go through each one together.
Create Localized RoutesFirst, we will need to create a localized route for each locale, i.e., route our English pages to paths with a /en/ prefix and the Spanish pages to a path with a /es/ prefix. So, for example, a path like my-site.com/recipes/mac-and-cheese/ will be replaced with localized routes, like my-site.com/en/recipes/mac-and-cheese/ for English and my-site.com/recipes/es/mac-and-cheese/ for Spanish.
In Part 1, we used the gatsby-theme-i18n plugin to automatically add localized routes for each page, and it worked perfectly. However, to make our own version, we first must know what happens underneath the hood of that plugin.
What gatsby-theme-i18n does is modify the createPages process to create a localized version of each page. However, what exactly is createPages?
When running npm run build in a fresh Gatsby site, you will see in the terminal what Gatsby is doing, and it looks something like this:
FreshRSS success open and validate gatsby-configs - 0.062 s
success load plugins - 0.915 s
success onPreInit - 0.021 s
success delete html and css files from previous builds - 0.030 s
success initialize cache - 0.034 s
success copy gatsby files - 0.099 s
success onPreBootstrap - 0.034 s
success source and transform nodes - 0.121 s
success Add explicit types - 0.025 s
success Add inferred types - 0.144 s
success Processing types - 0.110 s
success building schema - 0.365 s
success createPages - 0.016 s
success createPagesStatefully - 0.079 s
success onPreExtractQueries - 0.025 s
success update schema - 0.041 s
success extract queries from components - 0.333 s
success write out requires - 0.020 s
success write out redirect data - 0.019 s
success Build manifest and related icons - 0.141 s
success onPostBootstrap - 0.164 s
⠀
info bootstrap finished - 6.932 s
⠀
success run static queries - 0.166 s — 3/3 20.90 queries/second
success Generating image thumbnails — 6/6 - 1.059 s
success Building production JavaScript and CSS bundles - 8.050 s
success Rewriting compilation hashes - 0.021 s
success run page queries - 0.034 s — 4/4 441.23 queries/second
success Building static HTML for pages - 0.852 s — 4/4 23.89 pages/second
info Done building in 16.143999152 sec
As you can see, Gatsby does a lot to ship your React components into static files. In short, it takes five steps:
gatsby-config.js and the code in gatsby-node.js.nodes object./src/page JavaScript files.And, as you may notice, plugins like gatsby-theme-i18n intervene in step three, specifically when pages are created on createPages:
success createPages - 0.016 s
How exactly does gatsby-theme-i18n access createPages? Well, Gatsby exposes an onCreatePage event handler on the gatsby-node.js to read and modify pages when they are being created.
Learn more about creating and modifying pages and the Gatsby building process over at Gatsby’s official documentation.
onCreatePageThe createPages process can be modified in the gatsby-node.js file through the onCreatePage API. In short, onCreatePage is a function that runs each time a page is created by Gatsby. Here’s how it looks:
// ./gatsby-node.js
exports.onCreatePage = ({ page, actions }) => {
const { createPage, deletePage } = actions;
// etc.
};
It takes two parameters inside an object:
page holds the information of the page that’s going to be created, including its context, path, and the React component associated with it.actions holds several methods for editing the site’s state. In the Gatsby docs, you can see all available methods. For this example we’re making, we will be using two methods: createPage and deletePage, both of which take a page object as the only parameter and, as you might have deduced, they create or delete the page.So, if we wanted to add a new context to all pages, it would translate to deleting the pages being created and replacing them with new ones that have the desired context:
exports.onCreatePage = ({ page, actions }) => {
const { createPage, deletePage } = actions;
deletePage(page);
createPage({
...page,
context: {
...page.context,
category: `vegan`,
},
});
};
Since we need to create English and Spanish versions of each page, it would translate to deleting every page and creating two new ones, one for each locale. And to differentiate them, we will assign them a localized route by adding the locale at the beginning of their path.
Let’s start by creating a new gatsby-node.js file in the project’s root directory and adding the following code:
// ./gatsby-node.js
const locales = ["en", "es"];
exports.onCreatePage = ({page, actions}) => {
const {createPage, deletePage} = actions;
deletePage(page);
locales.forEach((locale) => {
createPage({
...page,
path: `${locale}${page.path}`,
});
});
};
Note: Restarting the development server is required to see the changes.
Now, if we go to http://localhost:8000/en/ or http://localhost:8000/es/, we will see all our content there. However, there is a big caveat. Specifically, if we head back to the non-localized routes — like http://localhost:8000/ or http://localhost:8000/recipes/mac-and-cheese/ — Gatsby will throw a runtime error instead of the usual 404 page provided by Gatsby. This is because we deleted our 404 page in the process of deleting all of the other pages!
Well, the 404 page wasn’t exactly deleted because we can still access it if we go to http://localhost:8000/en/404 or http://localhost:8000/es/404. However, we deleted the original 404 page and created two localized versions. Now Gatsby doesn’t know they are supposed to be 404 pages.
To solve it, we need to do something special to the 404 pages at onCreatePage.
Besides a path, every page object has another property called matchPath that Gatsby uses to match the page on the client side, and it is normally used as a fallback when the user reaches a non-existing page. For example, a page with a matchPath property of /recipes/* (notice the wildcard *) will be displayed on each route at my-site.com/recipes/ that doesn’t have a page. This is useful for making personalized 404 pages depending on where the user was when they reached a non-existing page. For instance, social media could display a usual 404 page on my-media.com/non-existing but display an empty profile page on my-media.com/user/non-existing. In this case, we want to display a localized 404 page depending on whether or not the user was on my-site.com/en/not-found or my-site.com/es/not-found.
The good news is that we can modify the matchPath property on the 404 pages:
// gatsby-node.js
const locales = [ "en", "es" ];
exports.onCreatePage = ({ page, actions }) => {
const { createPage, deletePage } = actions;
deletePage(page);
locales.forEach((locale) => {
const matchPath = page.path.match(/^\/404\/$/) ? (locale === "en" ? /* : /${locale}/*) : page.matchPath;
createPage({
...page,
path: ${locale}${page.path},
matchPath,
});
});
};
This solves the problem, but what exactly did we do in matchpath? The value we are assigning to the matchPath is asking:
/404/?This results in the English 404 page having a matchPath of /*, which will be our default 404 page; meanwhile, the Spanish version will have matchPath equal /es/* and will only be rendered if the user is on a route that begins with /es/, e.g., my-site.com/es/not-found. Now, if we restart the server and head to a non-existing page, we will be greeted with our usual 404 page.
Besides fixing the runtime error, doing leave us with the possibility of localizing the 404 page, which we didn’t achieve in Part 1 with the gatsby-theme-i18n plugin. That’s already a nice improvement we get by not using a plugin!
Now that we have localized routes, you may notice that both http://localhost:8000/en/ and http://localhost:8000/es/ are querying English and Spanish blog posts. This is because we aren’t filtering our Markdown content on the page’s locale. We solved this in Part 1, thanks to gatsby-theme-i18n injecting the page’s locale on the context of each page, making it available to use as a query variable on the GraphQL query.
In this case, we can also add the locale into the page’s context in the createPage method:
// gatsby-node.js
const locales = [ "en", "es" ];
exports.onCreatePage = ({page, actions}) => {
const { createPage, deletePage } = actions;
deletePage(page);
locales.forEach((locale) => {
const matchPath = page.path.match(/^\/404\/$/) ? (locale === "en" ? /* : /${locale}/*) : page.matchPath;
createPage({
...page,
path: ${locale}${page.path},
context: {
...page.context,
locale,
},
matchPath,
});
});
};
Note: Restarting the development server is required to see the changes.
From here, we can filter the content on both the homepage and blog posts, which we explained thoroughly in Part 1. This is the index page query:
query IndexQuery($locale: String) {
allMarkdownRemark(filter: {frontmatter: {locale: {eq: $locale}}}) {
nodes {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
}
}
}
And this is the {markdownRemark.frontmatter__slug}.js page query:
query RecipeQuery($frontmatter__slug: String, $locale: String) {
markdownRemark(frontmatter: {slug: {eq: $frontmatter__slug}, locale: {eq: $locale}}) {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
html
}
}
Now, if we head to http://localhost:8000/en/ or http://localhost:8000/es/, we will only see our English or Spanish posts, depending on which locale we are on.
However, if we try to click on any recipe, it will take us to a 404 page since the links are still pointing to the non-localized recipes. In Part 1, gatsby-theme-i18n gave us a LocalizedLink component that worked exactly like Gatsby’s Link but pointed to the current locale, so we will have to create a LocalizedLink component from scratch. Luckily is pretty easy, but we will have to make some preparation first.
For the LocalizedLink to work, we will need to know the page’s locale at all times, so we will create a new context that holds the current locale, then pass it down to each component. We can implement it on wrapPageElement in the gatsby-browser.js and gatsby-ssr.js Gatsby files. The wrapPageElement is the component that wraps our entire page element. However, remember that Gatsby recommends setting context providers inside wrapRootElement, but in this case, only wrapPageEement can access the page’s context where the current locale can be found.
Let’s create a new directory at ./src/context/ and add a LocaleContext.js file in it with the following code:
// ./src/context/LocaleContext.js
import * as React from "react";
import { createContext } from "react";
export const LocaleContext = createContext();
export const LocaleProvider = ({ locale, children }) => {
return <LocaleContext.Provider value={locale}>{children}</LocaleContext.Provider>;
};
Next, we will set the page’s context at gatsby-browser.js and gatsby-ssr.js and pass it down to each component:
// ./gatsby-browser.js & ./gatsby-ssr.js
import * as React from "react";
import { LocaleProvider } from "./src/context/LocaleContext";
export const wrapPageElement = ({ element }) => {
const {locale} = element.props.pageContext;
return <LocaleProvider locale={locale}>{element}</LocaleProvider>;
};
Note: Restart the development server to load the new files.
LocalizedLinkNow let’s make sure that the locale is available in the LocalizedLink component, which we will create in the ./src/components/LocalizedLink.js file:
// ./src/components/LocalizedLink.js
import * as React from "react";
import { useContext } from "react";
import { Link } from "gatsby";
import { LocaleContext } from "../context/LocaleContext";
export const LocalizedLink = ({ to, children }) => {
const locale = useContext(LocaleContext);
return <Link to={`/${locale}${to}`}>{children}</Link>;
};
We can use our LocalizedLink at RecipePreview.js and 404.js just by changing the imports:
// ./src/components/RecipePreview.js
import * as React from "react";
import { LocalizedLink as Link } from "./LocalizedLink";
import { GatsbyImage, getImage } from "gatsby-plugin-image";
export const RecipePreview = ({ data }) => {
const { cover_image, title, slug } = data;
const cover_image_data = getImage(cover_image.image.childImageSharp.gatsbyImageData);
return (
<Link to={/recipes/${slug}}>
<h1>{title}</h1>
<GatsbyImage image={cover_image_data} alt={cover_image.alt} />
</Link>
);
};
// ./src/pages/404.js
import * as React from "react";
import { LocalizedLink as Link } from "../components/LocalizedLink";
const NotFoundPage = () => {
return (
<main>
<h1>Page not found</h1>
<p>
Sorry 😔 We were unable to find what you were looking for.
<br />
<Link to="/">Go Home</Link>.
</p>
</main>
);
};
export default NotFoundPage;
export const Head = () => <title>Not Found</title>;
As you may have noticed, we deleted the non-localized pages and replaced them with localized ones, but by doing so, we left the non-localized routes empty with a 404 page. As we did in Part 1, we can solve this by setting up redirects at gatbsy-node.js to take users to the localized version. However, this time we will create a redirect for each page instead of creating a redirect that covers all pages.
These are the redirects from Part 1:
// ./gatsby-node.js
exports.createPages = async ({ actions }) => {
const { createRedirect } = actions;
createRedirect({
fromPath: `/*`,
toPath: `/en/*`,
isPermanent: true,
});
createRedirect({
fromPath: `/*`,
toPath: `/es/*`,
isPermanent: true,
conditions: {
language: [`es`],
},
});
};
// etc.
These are the new localized redirects:
// ./gatsby-node.js
exports.onCreatePage = ({ page, actions }) => {
// Create localize version of pages...
const { createRedirect } = actions;
createRedirect({
fromPath: page.path,
toPath: `/en${page.path}`,
isPermanent: true,
});
createRedirect({
fromPath: page.path,
toPath: `/es${page.path}`,
isPermanent: true,
conditions: {
language: [`es`],
},
});
};
// etc.
We won’t see the difference right away since redirects don’t work in development, but if we don’t create a redirect for each page, the localized 404 pages won’t work in production. We didn’t have to do this same thing in Part 1 since gatsby-theme-i18n didn’t localize the 404 page the way we did.
Another vital feature to add is a language selector component to toggle between the two locales. However, making a language selector isn’t completely straightforward because:
/en/recipes/pizza,recipes/pizza part, and/es/recipes/pizza.Similar to Part 1, we will have to access the page’s location information (URL, HREF, path, and so on) in all of our components, so it will be necessary to set up another context provider at the wrapPageElement function to pass down the location object through context on each page. A deeper explanation can be found in Part 1.
First, we will create the location context at ./src/context/LocationContext.js:
// ./src/context/LocationContext.js
import * as React from "react";
import { createContext } from "react";
export const LocationContext = createContext();
export const LocationProvider = ({ location, children }) => {
return <LocationContext.Provider value={location}>{children}</LocationContext.Provider>;
};
Next, let’s pass the page’s location object to the provider’s location attribute on each Gatsby file:
// ./gatsby-ssr.js & ./gatsby-browser.js
import * as React from "react";
import { LocaleProvider } from "./src/context/LocaleContext";
import { LocationProvider } from "./src/context/LocationContext";
export const wrapPageElement = ({ element, props }) => {
const { location } = props;
const { locale } = element.props.pageContext;
return (
<LocaleProvider locale={locale}>
<LocationProvider location={location}>{element}</LocationProvider>
</LocaleProvider>
);
};
For the next step, it will come in handy to create a file with all our i18n details, such as the locale code or the local name. We can do it in a new config.js file in a new i18n/ directory in the root directory of the project.
// ./i18n/config.js
export const config = [
{
code: "en",
hrefLang: "en-US",
name: "English",
localName: "English",
},
{
code: "es",
hrefLang: "es-ES",
name: "Spanish",
localName: "Español",
},
];
LanguageSelector ComponentThe last thing is to remove the locale (i.e., es or en) from the path (e.g., /es/recipes/pizza or /en/recipes/pizza). Using the following simple but ugly regex, we can remove all the /en/ and /es/ at the beginning of the path:
/(\/e(s|n)|)(\/*|)/
It’s important to note that the regex pattern only works for the en and es combination of locales.
Now we can create our LanguageSelector component at ./src/components/LanguageSelector.js:
// ./src/components/LanguageSelector.js
import * as React from "react";
import { useContext } from "react";
// 1
import { config } from "../../i18n/config";
import { Link } from "gatsby";
import { LocationContext } from "../context/LocationContext";
import { LocaleContext } from "../context/LocaleContext";
export const LanguageSelector = () => {
// 2
const locale = useContext(LocaleContext);
// 3
const { pathname } = useContext(LocationContext);
// 4
const removeLocalePath = /(\/e(s|n)|)(\/*|)/;
const pathnameWithoutLocale = pathname.replace(removeLocalePath, "");
// 5
return (
<div>
{ config.map(({code, localName}) => {
return (
code !== locale && (
<Link key={code} to={`/${code}/${pathnameWithoutLocale}`}>
{localName}
</Link>
)
);
}) }
</div>
);
};
Let’s break down what is happening in that code:
./i18n/config.js file instead of the useLocalization hook that was provided by the gatsby-theme-i18n plugin in Part 1./en/recipes/pizza).recipes/pizza).Link to the desired locale.Now, inside our gatsby-ssr.js and gatsby-browser.js files, we can add our LanguageSelector, so it is available globally on the site at the top of all pages:
// ./gatsby-ssr.js & ./gatsby-browser.js
import * as React from "react";
import { LocationProvider } from "./src/context/LocationContext";
import { LocaleProvider } from "./src/context/LocaleContext";
import { LanguageSelector } from "./src/components/LanguageSelector";
export const wrapPageElement = ({ element, props }) => {
const { location } = props;
const { locale } = element.props.pageContext;
return (
<LocaleProvider locale={locale}>
<LocationProvider location={location}>
<LanguageSelector />
{element}
</LocationProvider>
</LocaleProvider>
);
};
The last thing to do would be to localize the static content on our site, like the page titles and headers. To do this, we will need to save our translations in a file and find a way to display the correct one depending on the page’s locale.
In Part 1, we used the react-intl package for adding our translations, but we can do the same thing from scratch. First, we will need to create a new translations.js file in the /i18n folder that holds all of our translations.
We will create and export a translations object with two properties: en and es, which will hold the translations as strings under the same property name.
// ./i18n/translations.js
export const translations = {
en: {
index_page_title: "Welcome to my English cooking blog!",
index_page_subtitle: "Written by Juan Diego Rodríguez",
not_found_page_title: "Page not found",
not_found_page_body: "😔 Sorry, we were unable find what you were looking for.",
not_found_page_back_link: "Go Home",
},
es: {
index_page_title: "¡Bienvenidos a mi blog de cocina en español!",
index_page_subtitle: "Escrito por Juan Diego Rodríguez",
not_found_page_title: "Página no encontrada",
not_found_page_body: "😔 Lo siento, no pudimos encontrar lo que buscabas",
not_found_page_back_link: "Ir al Inicio",
},
};
We know the page’s locale from the LocaleContext we set up earlier, so we can load the correct translation using the desired property name.
The cool thing is that no matter how many translations we add, we won’t bloat our site’s bundle size since Gatsby builds the entire app into a static site.
// ./src/pages/index.js
// etc.
import { LocaleContext } from "../context/LocaleContext";
import { useContext } from "react";
import { translations } from "../../i18n/translations";
const IndexPage = ({ data }) => {
const recipes = data.allMarkdownRemark.nodes;
const locale = useContext(LocaleContext);
return (
<main>
<h1>{translations[locale].index_page_title}</h1>
<h2>{translations[locale].index_page_subtitle}</h2>
{recipes.map(({frontmatter}) => {
return <RecipePreview key={frontmatter.slug} data={frontmatter} />;
})}
</main>
);
};
// etc.
// ./src/pages/404.js
// etc.
import { LocaleContext } from "../context/LocaleContext";
import { useContext } from "react";
import { translations } from "../../i18n/translations";
const NotFoundPage = () => {
const locale = useContext(LocaleContext);
return (
<main>
<h1>{translations[locale].not_found_page_title}</h1>
<p>
{translations[locale].not_found_page_body} <br />
<Link to="/">{translations[locale].not_found_page_back_link}</Link>.
</p>
</main>
);
};
// etc.
Note: Another way we can access the locale property is by using pageContext in the page props.
We ought to localize the site’s page titles the same way we localized our page content. However, in Part 1, we used react-helmet for the task since the LocaleContext isn’t available at the Gatsby Head API. So, to complete this task without resorting to a third-party plugin, we will take a different path. We’re unable to access the locale through the LocaleContext, but as I noted above, we can still get it with the pageContext property in the page props.
// ./src/page/index.js
// etc.
export const Head = ({pageContext}) => {
const {locale} = pageContext;
return <title>{translations[locale].index_page_title}</title>;
};
// etc.
// ./src/page/404.js
// etc.
export const Head = ({pageContext}) => {
const {locale} = pageContext;
return <title>{translations[locale].not_found_page_title}</title>;
};
// etc.
Remember that i18n also covers formatting numbers and dates depending on the current locale. We can use the Intl object from the JavaScript Internationalization API. The Intl object holds several constructors for formatting numbers, dates, times, plurals, and so on, and it’s globally available in JavaScript.
In this case, we will use the Intl.DateTimeFormat constructor to localize dates in blog posts. It works by creating a new Intl.DateTimeFormat object with the locale as its parameter:
const DateTimeFormat = new Intl.DateTimeFormat("en");
The new Intl.DateTimeFormat and other Intl instances have several methods, but the main one is the format method, which takes a Date object as a parameter.
const date = new Date();
console.log(new Intl.DateTimeFormat("en").format(date)); // 4/20/2023
console.log(new Intl.DateTimeFormat("es").format(date)); // 20/4/2023
The format method takes an options object as its second parameter, which is used to customize how the date is displayed. In this case, the options object has a dateStyle property to which we can assign "full", "long", "medium", or "short" values depending on our needs:
const date = new Date();
console.log(new Intl.DateTimeFormat("en", {dateStyle: "short"}).format(date)); // 4/20/23
console.log(new Intl.DateTimeFormat("en", {dateStyle: "medium"}).format(date)); // Apr 20, 2023
console.log(new Intl.DateTimeFormat("en", {dateStyle: "long"}).format(date)); // April 20, 2023
console.log(new Intl.DateTimeFormat("en", {dateStyle: "full"}).format(date)); // Thursday, April 20, 2023
In the case of our blog posts publishing date, we will set the dateStyle to "long".
// ./src/pages/recipes/{markdownRemark.frontmatter__slug}.js
// etc.
const RecipePage = ({ data, pageContext }) => {
const { html, frontmatter } = data.markdownRemark;
const { title, cover_image, date } = frontmatter;
const { locale } = pageContext;
const cover_image_data = getImage(cover_image.image.childImageSharp.gatsbyImageData);
return (
<main>
<h1>{title}</h1>
<p>{new Intl.DateTimeFormat(locale, { dateStyle: "long" }).format(new Date(date))}</p>
<GatsbyImage image={cover_image_data} alt={cover_image.alt} />
<p dangerouslySetInnerHTML={{__html: html}}></p>
</main>
);
};
// etc.
And just like that, we reduced the need for several i18n plugins to a grand total of zero. And we didn’t even lose any functionality in the process! If anything, our hand-rolled solution is actually more robust than the system of plugins we cobbled together in Part 1 because we now have localized 404 pages.
That said, both approaches are equally valid, but in times when Gatsby plugins are unsupported in some way or conflict with other plugins, it is sometimes better to create your own i18n solution. That way, you don’t have to worry about plugins that are outdated or left unmaintained. And if there is a conflict with another plugin, you control the code and can fix it. I’d say these sorts of benefits greatly outweigh the obvious convenience of installing a ready-made, third-party solution.
Internationalization, or i18n, is making your content understandable in other languages, regions, and cultures to reach a wider array of people. However, a more interesting question would be, “Why is i18n important?”. The answer is that we live in an era where hundreds of cultures interact with each other every day, i.e., we live in a globalized world. However, our current internet doesn’t satisfy its globalized needs.
Did you know that 60.4% of the internet is in English, but only 16.2% percent of the world speaks English?
Source: Visual Capitalist
Yes, it’s an enormous gap, and until perfect AI translators are created, the internet community must close it.
As developers, we must adapt our sites’ to support translations and formats for other countries, languages, and dialects, i.e., localize our pages. There are two main problems when implementing i18n on our sites.
my-site.com/es or en.my-site.com. How are we going to create pages for each locale?Fortunately, in the case of Gatsby and other static site generators, translations don’t bloat up the page bundle size since they are delivered as part of the static page. The rest of the problems are widely known, and there are a lot of plugins and libraries available to address them, but it can be difficult to choose one if you don’t know their purpose, what they can do, and if they are compatible with your existing codebase. That’s why in the following hands-on guide, we will see how to use several i18n plugins for Gatsby and review some others.
The StarterBefore showing what each plugin can do and how to use them, we first have to start with a base example. (You can skip this and download the starter here). For this tutorial, we will work with a site with multiple pages created from an array of data, like a blog or wiki. In my case, I choose a cooking blog that will initially have support only for English.
To get started, let’s start a plain JavaScript Gatsby project without any plugins at first.
npm init gatsby
cd my-new-site
For this project, we will create pages dynamically from markdown files. To be able to read and parse them to Gatsby’s data layer, we will need to use the gatsby-source-filesystem and gatsby-transformer-remark plugins. Here you can see a more in-depth tutorial.
npm i gatsby-source-filesystem gatsby-transformer-remark
Inside our gatsby-config.js file, we will add and configure our plugins to read all the files in a specified directory.
// ./gatsby-config.js
module.exports = {
//...
plugins: [
{
resolve: `gatsby-source-filesystem`,
options: {
name: `content`,
path: `${__dirname}/src/content`,
},
},
`gatsby-transformer-remark`,
],
};
As you can see, we will use a new ./src/content/ directory where we will save our posts. We will create a couple of folders with each recipe’s content in markdown files, like the following:
├── src
│ ├── content
| | ├── mac-and-cheese
| | | ├── cover.jpg
| | | ├── index.en.md
| | ├── burritos
| | | ├── cover.jpg
| | | ├── index.en.md
| | ├── pizza
| | | ├── cover.jpg
| | | ├── index.en.md
│ ├── pages
│ ├── images
Each markdown file will have the following structure:
---
slug: "mac-and-cheese"
date: "2023-01-20"
title: "How to make mac and cheese"
cover_image:
image: "./cover.jpg"
alt: "Macaroni and cheese"
locale: "en"
---
Step 1
Lorem ipsum...
You can see that the first part of the markdown file has a distinct structure and is surrounded by --- on both ends. This is called the frontmatter and is used to save the file’s metadata. In this case, the post’s title, date, locale, etc.
As you can see, we will be using a cover.jpg file for each post, so to parse and use the images, we will need to install the gatsby-plugin-image gatsby-plugin-sharp and gatsby-transformer-sharp plugins (I know there are a lot 😅).
npm i gatsby-plugin-image gatsby-plugin-sharp gatsby-transformer-sharp
We will also need to add them to the gatsby-config.js file.
// ./gatsby-config.js
module.exports = {
//...
plugins: [
{
resolve: `gatsby-source-filesystem`,
options: {
name: `content`,
path: `${__dirname}/src/content`,
},
},
`gatsby-plugin-sharp`,
`gatsby-transformer-sharp`,
`gatsby-transformer-remark`,
`gatsby-plugin-image`,
],
};
We can finally start our development server:
npm run develop
And go to http://localhost:8000/___graphql, where we can make the following query:
query Query {
allMarkdownRemark {
nodes {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
}
}
}
And get the following result:
{
"data": {
"allMarkdownRemark": {
"nodes": [
{
"frontmatter": {
"slug": "/mac-and-cheese",
"title": "How to make mac and cheese",
"date": "2023-01-20",
"cover_image": {
/* ... */
}
}
},
{
"frontmatter": {
"slug": "/burritos",
"title": "How to make burritos",
"date": "2023-01-20",
"cover_image": {
/* ... */
}
}
},
{
"frontmatter": {
"slug": "/pizza",
"title": "How to make Pizza",
"date": "2023-01-20",
"cover_image": {
/* ... */
}
}
}
]
}
}
}
Now the data is accessible through Gatsby’s data layer, but to access it, we will need to run a query from the ./src/pages/index.js page.
Go ahead and delete all the boilerplate on the index page. Let’s add a short header for our blog and create the page query:
// src/pages/index.js
import * as React from "react";
import {graphql} from "gatsby";
const IndexPage = () => {
return (
<main>
<h1>Welcome to my English cooking blog!</h1>
<h2>Written by Juan Diego Rodríguez</h2>
</main>
);
};
export const indexQuery = graphql`
query IndexQuery {
allMarkdownRemark {
nodes {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
}
}
}
`;
export default IndexPage;
The result from the query is injected into the IndexPage component as a props property called data. From there, we can render all the recipes’ information.
// src/pages/index.js
// ...
import {RecipePreview} from "../components/RecipePreview";
const IndexPage = ({data}) => {
const recipes = data.allMarkdownRemark.nodes;
return (
<main>
<h1>Welcome to my English cooking blog!</h1>
<h2>Written by Juan Diego Rodríguez</h2>
{recipes.map(({frontmatter}) => {
return <RecipePreview key={frontmatter.slug} data={frontmatter} />;
})}
</main>
);
};
// ...
The RecipePreview component will be the following in a new directory: ./src/components/:
// ./src/components/RecipePreview.js
import * as React from "react";
import {Link} from "gatsby";
import {GatsbyImage, getImage} from "gatsby-plugin-image";
export const RecipePreview = ({data}) => {
const {cover_image, title, slug} = data;
const cover_image_data = getImage(cover_image.image.childImageSharp.gatsbyImageData);
return (
<Link to={/recipes/${slug}}>
<h1>{title}</h1>
<GatsbyImage image={cover_image_data} alt={cover_image.alt} />
</Link>
);
};
If we go to http://localhost:8000/, we will see all our recipes listed, but now we have to create a custom page for each recipe. We can do it using Gatsby’s File System Route API. It works by writing a GraphQL query inside the page’s filename, generating a page for each query result. In this case, we will make a new directory ./src/pages/recipes/ and create a file called {markdownRemark.frontmatter__slug}.js. This filename translates to the following query:
query MyQuery {
allMarkdownRemark {
nodes {
frontmatter {
slug
}
}
}
}
And it will create a page for each recipe using its slug as the route.
Now we just have to create the post’s component to render all its data. First, we will use the following query:
query RecipeQuery {
markdownRemark {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
html
}
}
This will query the first markdown file available in our data layer, but to specify the markdown file needed for each page, we will need to use variables in our query. The File System Route API injects the slug in the page’s context in a property called frontmatter__slug. When a property is in the page’s context, it can be used as a query variable under a $ followed by the property name, so the slug will be available as $frontmatter__slug.
query RecipeQuery {
query RecipeQuery($frontmatter__slug: String) {
markdownRemark(frontmatter: {slug: {eq: $frontmatter__slug}}) {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
html
}
}
}
The page’s component is pretty simple. We just get the query data from the component’s props. Displaying the title and date is straightforward, and the html can be injected into a p tag. For the image, we just have to use the GatsbyImage component exposed by the gatsby-plugin-image.
// src/pages/recipes/{markdownRemark.frontmatter__slug}.js
const RecipePage = ({data}) => {
const {html, frontmatter} = data.markdownRemark;
const {title, cover_image, date} = frontmatter;
const cover_image_data = getImage(cover_image.image.childImageSharp.gatsbyImageData);
return (
<main>
<h1>{title}</h1>
<p>{date}</p>
<GatsbyImage image={cover_image_data} alt={cover_image.alt} />
<p dangerouslySetInnerHTML={{__html: html}}></p>
</main>
);
};
//...
The last thing is to use the Gatsby Head API to change the page’s title to the recipe’s title. This can be easily done since the query’s data is also available in the Head component.
// src/pages/recipes/{markdownRemark.frontmatter__slug}.js
//...
export const Head = ({data}) => <title>{data.markdownRemark.frontmatter.title}</title>;
Summing all up results in the following code:
// src/pages/recipes/{markdownRemark.frontmatter__slug}.js
import * as React from "react";
import {GatsbyImage, getImage} from "gatsby-plugin-image";
import {graphql} from "gatsby";
const RecipePage = ({data}) => {
const {html, frontmatter} = data.markdownRemark;
const {title, cover_image, date} = frontmatter;
const cover_image_data = getImage(cover_image.image.childImageSharp.gatsbyImageData);
return (
<main>
<h1>{title}</h1>
<p>{date}</p>
<GatsbyImage image={cover_image_data} alt={cover_image.alt} />
<p dangerouslySetInnerHTML={{__html: html}}></p>
</main>
);
};
export const recipeQuery = graphqlquery RecipeQuery($frontmatter__slug: String) {
markdownRemark(frontmatter: {slug: {eq: $frontmatter__slug}}) {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
html
}
};
export default RecipePage;
export const Head = ({data}) => <title>{data.markdownRemark.frontmatter.title}</title>;
With all this finished, we have a functioning recipe blog in English. Now we will use each plugin to add i18n features and localize the site (for this tutorial) for Spanish speakers. But first, we will make a Spanish version for each markdown file in ./src/content/. Leaving a structure like the following:
├── src
│ ├── content
| | ├── mac-and-cheese
| | | ├── cover.jpg
| | | ├── index.en.md
| | | ├── index.es.md
| | ├── burritos
| | | ├── cover.jpg
| | | ├── index.en.md
| | | ├── index.es.md
| | ├── pizza
| | | ├── cover.jpg
| | | ├── index.en.md
| | | ├── index.es.md
│ ├── pages
│ ├── images
Inside our new Spanish markdown files, we will have the same structure in our frontmatter but translated to our new language and change the locale property in the frontmatter to es. However, it’s important to note that the slug field must be the same in each locale.
gatsby-plugin-i18n
This plugin is displayed in Gatsby’s Internationalization Guide as its first option when implementing i18n routes. The purpose of this plugin is to create localized routes by adding a language code in each page filename, so, for example, a ./src/pages/index.en.js file would result in a my-site.com/en/ route.
I strongly recommend not using this plugin. It is outdated and hasn’t been updated since 2019, so it is kind of a disappointment to see it promoted as one of the main solutions for i18n in Gatsby’s official documentation. It also breaks the File System API, so you must use another method for creating pages, like the createPages function in the Gatsby Node API. Its only real use would be to create localized routes for certain pages, but considering that you must create a file for each page and each locale, it would be impossible to manage them on even medium sites. A 20 pages site with support for five languages would need 100 files!
gatsby-theme-i18n
Another plugin for implementing localized routes is gatsby-theme-i18n, which will be pretty easy to use in our prior example.
We will first need to install the gatsby-theme-i18n plugin and the gatsby-plugin-react-helmet and react-helmet plugins to help add useful language metadata in our <head> tag.
npm install gatsby-theme-i18n gatsby-plugin-react-helmet react-helmet
Next, we can add it to the gatsby-config.js:
// ./gatsby-config.js
module.exports = {
//...
plugins: [
//other plugins ...
{
resolve: `gatsby-theme-i18n`,
options: {
defaultLang: `en`,
prefixDefault: true,
configPath: require.resolve(`./i18n/config.json`),
},
},
],
};
As you can see, the plugin configPath points to a JSON file. This file will have all the information necessary to add each locale. We will create it in a new ./i18n/ directory at the root of our project:
[
{
"code": "en",
"hrefLang": "en-US",
"name": "English",
"localName": "English",
"langDir": "ltr",
"dateFormat": "MM/DD/YYYY"
},
{
"code": "es",
"hrefLang": "es-ES",
"name": "Spanish",
"localName": "Español",
"langDir": "ltr",
"dateFormat": "DD.MM.YYYY"
}
]
Note: To see changes in the gatsby-config.js file, we will need to restart the development server.
And just as simple as that, we added i18n routes to all our pages. Let’s head to http://localhost:8000/es/ or http://localhost:8000/en/ to see the result.
At first glance, you will see a big problem: the Spanish and English pages have all the posts from both locales because we aren’t filtering the recipes for a specific locale, so we get all the available recipes. We can solve this by once again adding variables to our GraphQL queries. The gatsby-theme-i18n injects the current locale into the page’s context, making it available to use as a query variable under the $locale name.
index page query:
query IndexQuery($locale: String) {
allMarkdownRemark(filter: {frontmatter: {locale: {eq: $locale}}}) {
nodes {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
}
}
}
{markdownRemark.frontmatter__slug}.js page query:
query RecipeQuery($frontmatter__slug: String, $locale: String) {
markdownRemark(frontmatter: {slug: {eq: $frontmatter__slug}, locale: {eq: $locale}}) {
frontmatter {
slug
title
date
cover_image {
image {
childImageSharp {
gatsbyImageData
}
}
alt
}
}
html
}
}
You will also notice that all Gatsby links are broken since they point to the non-localized routes instead of the new routes, so they will direct the user to a 404 page. To solve this, gatsby-theme-i18n exposes a LocalizedLink component that works exactly like Gatsby’s Link but points to the current locale. We just have to switch each Link component for a LocalizedLink.
// ./src/components/RecipePreview.js
+ import {LocalizedLink as Link} from "gatsby-theme-i18n";
- import {Link} from "gatsby";
//...
Another vital feature to add will be a component to change from one locale to another. However, making a language selector isn’t completely straightforward. First, we will need to know the current page’s path, like /en/recipes/pizza, to extract the recipes/pizza part and add the desired locale, getting /es/recipes/pizza.
To access the page’s location information (URL, HREF, path, and so on) in all our components, we will need to use the wrapPageElement function available in the gatsby-browser.js and gatsby-ssr.js files. In short, this function lets you access the props used on each page, including a location object. We can set up a context provider with the location information and pass it down to all components.
First, we will create the location context in a new directory: ./src/context/.
// ./src/context/LocationContext.js
import * as React from "react";
import {createContext} from "react";
export const LocationContext = createContext();
export const LocationProvider = ({location, children}) => {
return <LocationContext.Provider value={location}>{children}</LocationContext.Provider>;
};
As you can imagine, we will pass the page’s location object to the provider’s location attribute on each Gatsby file:
// ./gatsby-ssr.js & ./gatsby-browser.js
import * as React from "react";
import {LocationProvider} from "./src/context/LocationContext";
export const wrapPageElement = ({element, props}) => {
const {location} = props;
return <LocationProvider location={location}>{element}</LocationProvider>;
};
Note: Since we just created the gatsby-ssr.js and gatsby-browser.js files, we will need to restart the development server.
Now the page’s location is available in all components through context, and we can use it in our language selector. We have also to pass down the current locale to all components, and the gatsby-theme-i18n exposes a useful useLocalization hook that let you access the current locale and the i18n config. However, a caveat is that it can’t get the current locale on Gatsby files like gatsby-browser.js and gatsby-ssr.js, only the i18n config.
Ideally, we would want to render our language selector using wrapPageElement so it is available on all pages, but we can’t use the useLocazication hook. Fortunately, the wrapPageElement props argument also exposes the page’s context and, inside, its current locale.
Let’s create another context to pass down the locale:
// ./src/context/LocaleContext.js
import * as React from "react";
import {createContext} from "react";
export const LocaleContext = createContext();
export const LocaleProvider = ({locale, children}) => {
return <LocaleContext.Provider value={locale}>{children}</LocaleContext.Provider>;
};
And use it in our wrapPageElement function:
// ./gatsby-ssr.js & ./gatsby-browser.js
import * as React from "react";
import {LocationProvider} from "./src/context/LocationContext";
import {LocaleProvider} from "./src/context/LocaleContext";
export const wrapPageElement = ({element, props}) => {
const {location} = props;
const {locale} = element.props.pageContext;
return (
<LocationProvider location={location}>
<LocaleProvider locale={locale}>{element}</LocaleProvider>
</LocationProvider>
);
};
The last thing is how to remove the locale (es or en) from the path (/es/recipes/pizza). Using the following simple but ugly regex, we can remove all the /en/ and /es/ at the beginning of the path:
/(\/e(s|n)|)(\/*|)/
It’s important to note that the regex pattern only works for the en and es combination of locales.
Now we have to create our LanguageSelector.js:
// ./src/components/LanguageSelector
import * as React from "react";
import {useContext} from "react";
import {useLocalization} from "gatsby-theme-i18n";
import {Link} from "gatsby";
import {LocationContext} from "../context/LocationContext";
import {LocaleContext} from "../context/LocaleContext";
export const LanguageSelector = () => {
const {config} = useLocalization();
const locale = useContext(LocaleContext);
const {pathname} = useContext(LocationContext);
const removeLocalePath = /(\/e(s|n)|)(\/*|)/;
const pathnameWithoutLocale = pathname.replace(removeLocalePath, "");
return (
<div>
{config.map(({code, localName}) => {
return (
code !== locale && (
<Link key={code} to={`/${code}/${pathnameWithoutLocale}`}>
{localName}
</Link>
)
);
})}
</div>
);
};
Let’s break down what is happening:
useLocalization hook./en/recipes/pizza).recipes/pizza).Link to the desired locale.Now inside our gatsby-ssr.js and gatsby-browser.js files, we can add our LanguageSelector:
// ./gatsby-ssr.js & ./gatsby-browser.js
import * as React from "react";
import {LocationProvider} from "./src/context/LocationContext";
import {LocaleProvider} from "./src/context/LocaleContext";
import {LanguageSelector} from "./src/components/LanguageSelector";
export const wrapPageElement = ({element, props}) => {
const {location} = props;
const {locale} = element.props.pageContext;
return (
<LocationProvider location={location}>
<LocaleProvider locale={locale}>
<LanguageSelector />
{element}
</LocaleProvider>
</LocationProvider>
);
};
The last detail to address is that now the non-i18n routes like http://localhost:8000/ or http://localhost:8000/recipes/pizza are empty. To solve this, we can redirect the user to their desired locale using Gatsby’s redirect in gatsby-node.js.
// ./gatsby-node.js
exports.createPages = async ({actions}) => {
const {createRedirect} = actions;
createRedirect({
fromPath: `/*`,
toPath: `/en/*`,
isPermanent: true,
});
createRedirect({
fromPath: `/*`,
toPath: `/es/*`,
isPermanent: true,
conditions: {
language: [`es`],
},
});
};
Note: Redirects only work in production! Not in the local development server.
With this, each page that doesn’t start with the English or Spanish locale will be redirected to a localized route. The wildcard * at the end of each route says it will redirect them to the same path, e.g., it will redirect /recipes/mac-and-cheese/ to /en/recipes/mac-and-cheese/. Also, it will check for the specified language in the request’s origin and redirect to the locale if available; else, it will default to English.
react-intl
react-intl is an internationalization library for any React app that can be used with Gatsby without any extra configuration. It provides a component to handle translations and many more to format numbers, dates, times, etc. Like the following:
FormattedNumber,FormattedDate,FormattedTime.It works by adding a provider called IntlProvider to pass down the current locale to all the react-intl components. Among others, the provider takes three main attributes:
messagelocaledefaultLocaleSo, for example:
<IntlProvider messages={{}} locale="es" defaultLocale="en" >
<FormattedNumber value={15000} />
<br />
<FormattedDate value={Date.now()} />
<br />
<FormattedTime value={Date.now()} />
<br />
</IntlProvider>,
Will format the given values to Spanish and render:
15.000
23/1/2023
19:40
But if the locale attribute in IntlProvider was en, it would format the values to English and render:
15,000
1/23/2023
7:42 PM
Pretty cool and simple!
react-intl With GatsbyTo showcase how the react-intl works with Gatsby, we will continue from our prior example using gatsby-theme-i18n.
We first will need to install the react-intl package:
npm i react-intl
Secondly, we have to write our translations, and in this case, we just have to translate the title and subtitle on the index.js page. To do so, we will create a file called messajes.js in the ./i18n/ directory:
// ./i18n/messages.js
export const messages = {
en: {
index_page_title: "Welcome to my English cooking blog!",
index_page_subtitle: "Written by Juan Diego Rodríguez",
},
es: {
index_page_title: "¡Bienvenidos a mi blog de cocina en español!",
index_page_subtitle: "Escrito por Juan Diego Rodríguez",
},
};
Next, we have to set up the IntlProvider in the gatsby-ssr.js and gatsby-browser.js files:
// ./gatsby-ssr.js & ./gatsby-browser.js
import * as React from "react";
import {LocationProvider} from "./src/context/LocationContext";
import {LocaleProvider} from "./src/context/LocaleContext";
import {IntlProvider} from "react-intl";
import {LanguageSelector} from "./src/components/LanguageSelector";
import {messages} from "./i18n/messages";
export const wrapPageElement = ({element, props}) => {
const {location} = props;
const {locale} = element.props.pageContext;
return (
<LocationProvider location={location}>
<LocaleProvider locale={locale}>
<IntlProvider messages={messages[locale]} locale={locale} defaultLocale="en">
<LanguageSelector />
{element}
</IntlProvider>
</LocaleProvider>
</LocationProvider>
);
};
And use the FormattedMessage component with an id attribute holding the desired translation key name.
// ./src/pages/index.js
// ...
import {FormattedMessage} from "react-intl";
const IndexPage = ({data}) => {
const recipes = data.allMarkdownRemark.nodes;
return (
<main>
<h1>
<FormattedMessage id="index_page_title" />
</h1>
<h2>
<FormattedMessage id="index_page_subtitle" />
</h2>
{recipes.map(({frontmatter}) => {
return <RecipePreview key={frontmatter.slug} data={frontmatter} />;
})}
</main>
);
};
// ...
And as simple as that, our translations will be applied depending on the current user’s locale. However, i18n isn’t only translating all the text to other languages but also adapting to the way numbers, dates, currency, and so on are formatted in the user’s regions. In our example, we can format the date on each recipe page to be formatted according to the current locale using the FormattedDate component.
// ./src/pages/recipes/{markdownRemark.frontmatter__slug}.js
//...
import {FormattedDate} from "react-intl";
const RecipePage = ({data}) => {
const {html, frontmatter} = data.markdownRemark;
const {title, cover_image, date} = frontmatter;
const cover_image_data = getImage(cover_image.image.childImageSharp.gatsbyImageData);
return (
<main>
<h1>{title}</h1>
<FormattedDate value={date} year="numeric" month="long" day="2-digit" />
<GatsbyImage image={cover_image_data} alt={cover_image.alt} />
<p dangerouslySetInnerHTML={{__html: html}}></p>
</main>
);
};
//...
As you can see, we feed the component the raw date and specify how we want to display it. Then the component will automatically format it to the correct locale. And with the year, month, and day attributes, we can further customize how to display our date. In our example, the date 19-01-2023 will be formatted the following way:
English: January 19, 2023
Spanish: 19 de enero de 2023
If we want to add a localized string around the date, we can use react-intl arguments. Arguments are a way to add dynamic data inside our react-intl messages. It works by adding curly braces {} inside a message.
The arguments follow this pattern { key, type, format }, in which
key is the data to be formatted;type specifies if the key is going to be a number, date, time, and so on;format further specifies the format, e.g., if a date is going to be written like 10/05/2023 or October 5, 2023.In our case, we will name our key postedOn, and it will be a date type in a long format:
// ./i18n/messages.js
export const messages = {
en: {
// ...
recipe_post_date: "Written on {postedOn, date, long}",
},
es: {
// ...
recipe_post_date: "Escrito el {postedOn, date, long}",
},
};
// ./src/pages/recipes/{markdownRemark.frontmatter__slug}.js
//...
import {FormattedMessage} from "react-intl";
const RecipePage = ({data}) => {
const {html, frontmatter} = data.markdownRemark;
const {title, cover_image, date} = frontmatter;
const cover_image_data = getImage(cover_image.image.childImageSharp.gatsbyImageData);
return (
<main>
<h1>{title}</h1>
<FormattedMessage id="recipe_post_date" values={{postedOn: new Date(date)}} />
<GatsbyImage image={cover_image_data} alt={cover_image.alt} />
<p dangerouslySetInnerHTML={{__html: html}}></p>
</main>
);
};
//...
Note: For the date to work, we will need to create a new Date object with our date as its only argument.
The last thing you may have noticed is that the index page’s title isn’t localized. In the recipes pages’ case, this isn’t a problem since it queries the already localized title for each post, but the index page title doesn’t. Solving this can be tricky for two reasons:
react-intl since the IntlProvider doesn’t exist for components created inside the Head API.FormattedMessage component inside the title tag since it only allows a simple string value, not a component.However, there is a workaround for both problems:
react-helmet (which we installed with gatsby-theme-i18n) inside the page component where the IntlProvider is available.react-intl imperative API to get the messages as strings instead of the FormmatedMessage component. In this case, the imperative API exposes a useIntl hook which returns an intl object, and the intl.messages property holds all our messages too.So the index component would end up like this:
// ./src/pages/index.js
// ...
import {FormattedMessage, useIntl} from "react-intl";
import {Helmet} from "react-helmet";
const IndexPage = ({data}) => {
const intl = useIntl();
const recipes = data.allMarkdownRemark.nodes;
return (
<main>
<Helmet>
<title>{intl.messages.index_page_title}</title>
</Helmet>
<h1>
<FormattedMessage id="index_page_title" />
</h1>
<h2>
<FormattedMessage id="index_page_subtitle" />
</h2>
{recipes.map(({frontmatter}) => {
return <RecipePreview key={frontmatter.slug} data={frontmatter} />;
})}
</main>
);
};
// ...
react-i18next
react-i18next is a well-established library for adding i18n to our react sites, and it brings the same and more features, hooks, and utils of react-intl. However, a crucial difference is that to set up react-i18next, we will need to create a wrapper plugin in gatsby-node.js while you can use react-intl as soon as you install it, so I believe it’s a better option to use with Gatsby. However, there already are plugins to set up faster the react-i18next library like gatsby-plugin-react-i18next and gatsby-theme-i18n-react-i18next.
The current state of Gatsby and especially its plugin is precarious, and each year its popularity goes lower, so it’s important to know how to handle it and which plugins to use if you want to work with Gatsby. Despite all, I still believe Gatsby is a powerful tool and is still worth starting a new project with npm init gatsby.
I hope you found this guide useful and leave with a better grasp of i18n in Gatsby and with less of a headache. In the next article, we will explore an in-depth solution to i18n by creating your own i18n plugin!
