Codacy Badge Codacy Badge build version dependencies

A gatsby plugin for static i18n.

In particular, this plugin create a copy of every page for each locale, and passes to each page the current locale (and other info) through pageContext. It also includes a wrapped Link component that supports i18n and a LocalesInfoProvider that you can use to provide the locales info as React context.


With npm:

npm i gatsby-plugin-i18nstatic

With yarn:

yarn add gatsby-plugin-i18nstatic



Add the following section to your gatsby-config.js:

  resolve: "gatsby-plugin-i18nstatic",
    options: {
      locales: ["*your locales here*"],
      defaultLocale: "*your default locale*"

where the locales option is a list of all the locales you want to generates pages for, and defaultLocale is the locale to associate with the root (/) path of your app.

For example, say that we have a page called home. In this case the plugin would generate a page with the path /home with the english locale, and a page at /es/home with the spanish locale.

Of course, defaultLocale is optional: if you don’t want this behaviour, simply omit it.

An alternative to specifing the locales as an array is to instead use the localesFolder option (and if needed, also the ignoredFolders one), like this:

  resolve: "gatsby-plugin-i18nstatic",
    options: {
      localesFolder: `${__dirname}/src/locales`,
      ignoredFolders: ["_build"],
      defaultLocale: "en"

This way, the plugin will consider every directory in ${__dirname}/src/locales as a locale, while also ignoring _build.


This plugin also includes a couple of useful React components:

  • LocalesInfoProvider: provides locales info to children through React context.
  • Link: a lighweight wrapper around Gatsby’s Link component, with support for localized routes. Must be a child of LocalesInfoProvider.

If you need it, there’s also a useLocalesInfo hook.


This project is licensed under the MIT License - see the LICENSE for more details.

Special Thanks

This package is for the most part based on this blog post by Pedro Brandão.