Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub



Opinionated Gatsby theme which provides a full solution for localization in Gatsby. This theme is built upon the awesome gatsby-plugin-i18n and react-i18next and acts as a bridge between the two. I couldn’t find a full solution for localization with Gatsby which works the way I want it to, so I made a custom solution for my personal website and put everything I learned in this Gatsby theme in hopes to help out anyone who may struggle with the same.


This is a basic overview to get you started. For more advanced features or better documentation, please visit the full documentation.

Getting started

Using this plugin is really simple. First, install it by using npm install gatsby-theme-localization. Add this to your gatsby-config.js:

module.exports = {
  plugins: [
      resolve: `gatsby-theme-localization`,
      options: {
        languages: ['en', 'bg'],
        namespaces: ['translation', 'about'],
        localesDir: './src/locales',
        allowIndex: false,
        defaultLng: 'en',
        i18next: {
          // whatever you want to pass to react-i18next
          fallbackLng: 'en',
          debug: process.env.NODE_ENV !== 'production'
        i18nPlugin: {
          // whatever you want to pass to gatsby-plugin-i18n
          langKeyDefault: 'en',
          useLangKeyLayout: false

This is an example configuration for this plugin, but you can probably get away with even less.

That’s it! Your Gatsby-powered website now has localization!

How to use

Currently, the way to store your translations is in a JSON file (although in the future I want to add remote translations).

For each language your page has, create a file in pages following this pattern: [your page name].[language].js. An example of this is index.en.js. Inside your page component, you can use all of react-i18next’s features. For me, the most convenient way is to use the useTranslation hook. If your page is the same for all languages, you can just reexport your page component in all languages you want, although this is often not the case.

This theme exports a drop-in replacement for Gatsby’s link. In fact, it forwards all props to the original Gatsby link, except for the “to” prop, which is enhanced to prefix the current language. This feature can be disabled via the “prefixLanguage” prop.

In your locales folder, you need to create a folder for each language you support, and a JSON file for each namespace you want. It is important that all files exist, otherwise it will crash. This is intentional as I think it is better to crash your build rather than have missing texts.

How it works

gatsby-plugin-i18n creates the routes for each language but doesn’t do anything for the actual translations, so we are free to use any plugin we like. I18next handles the actual translation. My theme synchronizes the two awesome libraries. Make sure to read both plugins’ documentation to make use of their full capabilities.

Options API

For example usage, refer to the example gatsby-config.

Option Default Description
languages [] List of language you support
namespaces [] List of namespaces you support
allowIndex false This controls whether you want your ”/” route to be accessible. If not, redirect to the user’s preferred language
defaultLng ‘en’ Default language, used for a number of things (such as fallback when language cannot be detected)
localesDir ’./src/locales’ Directory where your JSON files are stored (relative to the root of your project)
i18next {} Object with options which will be passed to i18next
i18nPlugin {} Object with options which will be passed to gatsby-plugin-i18n
suspenseFallback undefined Path to fallback component for Suspense


Prop Default Description
prefixLanguage true Prefix language before url (e.g. “/about” -> “/en/about”)
preloadNamespaces [] Namespaces to preload on hover for faster loading


Licensed under the MIT License.

© 2023 Gatsby, Inc.