All You Need to Know About i18n with Gatsby

Internationalization (i18n) with Gatsby

Gatsby is a static site generator that uses the power of React to build any type of websites. Sites built with Gatsby are performant, easy to code and can leverage the vast React component ecosystem. That means we can use most of our favorite React based UI libraries to make them beautiful.

In this tutorial on i18n with Gatsby, we are going to build a small but beautiful blog that includes i18n components with an i18next library. Previously, we have seen some great examples of implementing react i18n. Now we can take a look at an example with static site generators like Gatsby. Additionally, we are going to see how we can integrate the Phrase In-Context Editor into our site and be able to browse the website and edit text along the way. The entire code is also available on Github.

Gatsby and Static Sites

As you may have already noticed, there is a big difference between dynamic and static websites. A static website contains web pages with fixed content. That is only Javascript, HTML and CSS. There is a server that hosts those static assets, but it does not have an engine to run scripts (node, python, etc..). However, there might be content retrieved from other sources other than the web-server hosting the site.

In terms of localization, we need to have a way we can show a page in a localized view with minimal duplication possible. For static sites, we may have some duplication as the content is rendered to HTML on deployment. Our job is to make it easy to extend and reuse.

Gatsby is a fully-featured static site generator that offers among other things:

  • Integrations with more than 120 backends
  • A React toolkit
  • Lightning-fast performance

Let us start layering down a basic site using Gatsby and how we can make it more localizable. First, let us start with the preliminaries.

Gatsby i18n with i18next – the easy way

Create a Gatsby site from a Gatsby starter.

Install Gatsby and create a new site

When the installation is complete go and edit the package.json and set the following dependencies:


The reason we do that is because we want to keep this tutorial working with this particular version of Gatsby. Otherwise we would have problems in the gatsby-cli tool installs non compatible versions in the future.

Recreate the package-lock.json by deleting and reinstalling:


Then you will have the following folder structure:

This is a basic site with no goodies.

Now the easiest way to add i18n support via the i18next is to use the gatsby-i18n-plugin that configures i18next as a HOC component called withi18next . We are going to wrap all our components with that HOC to make them localizable so that each component gets the local context from the i18next config. This library also offers some other helpers like a locale ware Head , Redirect , Language and Link elements.

Let’s start:

Install the required plugins.

Then replace the gatsby-config.js with the following contents:

Next, start replacing the Components with the i18next versions. Let’s start with layout.js.

As you can see, we use withTranslation HOC to pass the t helper to translate the messages. We also use the Head component that handles locale meta information to the head HTML element.

Let’s continue with the Header component.

Here we are using the Link component from the gatsby-plugin-i18next to provide links with the current language tag prepended.

We also use a LanguageSwitcher component which is a simple dropdown with all the available languages. When we click a language option we switch the locale.

Here the Language component provides the list of available languages, the current language and a function to change locale.

Now that we have created the components we can proceed with the main pages. Let’s start with the index.js Page.

Notice a few things here… We use a query that is a simple boilerplate code to retrieve the current locale messages from the filesystem. We also wrapped our component with the withI18next HOC that will initiate the i18next library on page load. This is needed for every public facing page as we need to activate this library on page refresh also.

Let’s continue with the page-2.js and 404.js

Last but not least, we need to provide the actual translation messages. We need to create some folders for the locale. Make a locale dir and add the following folder structure.

Then provide the translation messages for each locale.

Now we are ready to see our site in action. Start the development server and check the translations happening.


Adding the Phrase In-Context Editor

Phrase’s In-Context Editor is a translation tool that helps the process by providing useful contextual information, which improves the overall translation quality. You simply browse your website and edit text along the way.

Although there is no direct integration for Gatby we have a plugin offered from the Phrase team that for react-i18next and with a little bit of hacking we can add it to our site as well!.

First, install it.

Let’s see now how we can do that in simple steps.

First, we need to provide our own withI18next HOC that will do the same job as the original provide but it will add the PhraseAppProvider with the right config.

Create a new folder i18n in the src directory and add the following file.

The contents of the setupI18next.js file are only for initiating the i18next library from within the local codebase as they are not exported from the gatsby-i18next-plugin.

We need to replace all instances of withI18next with the one provided from the one we wrapped before. For example, here is the page-2.js component.

The window.PHRASEAPP_CONFIG need to be configured in the HTML root tree. In order for Gatsby to do that, we need to copy the .cache/default-html.js fileto the src and modify it for our own needs.

Add the following snippet just before the head element closes:

Finally, we need to load the Phrase In-Context Editor javascript library code to activate it. The same library offers a helpful component called PhraseAppInitializer that does that work for us. We only need to place it in a position that will be used once the application is loaded. For this example, we use the layout.js.

If you haven’t done that already, navigate to and sign up for a trial.

Once you set up your account, you can create a project and navigate to Project Settings to find your projectId key.

Use that to assign the projectId variable in the PHRASEAPP_CONFIG before you start the server.

When you navigate to the page, you will see a login modal and once you are authenticated, you will see the translated strings change to include edit buttons next to them. The In-Context Editor panel will show up as well.




In this article, we saw how to add localization in a Gatsby site with i18next the easy way. We also took a look at how we can integrate it in our workflow with the Phrase In-Context Editor. If you have any other questions left, do not hesitate to post a comment or drop me a line. Thank you for reading and see you again next time!

3.8 (76.67%) 6 votes