Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Official Plugin
View plugin on GitHub


A Gatsby theme for providing localization support via Lingui. This theme sets up Lingui’s context provider so that you can access your translations on every page.


Note: This theme is designed to work as an add-on to gatsby-theme-i18n and will not work without it! Please follow its setup instructions before starting with these here!

  1. Install the theme and its peerDependencies.
npm install gatsby-theme-i18n-lingui @lingui/react @lingui/core

Also install any devDependencies.

npm install --dev babel-preset-gatsby @lingui/macro @lingui/cli
  1. Add the configuration to your gatsby-config.js file:
module.exports = {
  plugins: [
      resolve: `gatsby-theme-i18n-lingui`,
      options: {
        localeDir: `./i18n/lingui`,
  1. Create a .linguirc file at the root of your project:
  "locales": ["your", "locales"],
  "catalogs": [
      "path": "<rootDir>/i18n/lingui/{locale}/messages",
      "include": ["<rootDir>/src"],
      "exclude": ["**/node_modules/**", "**/__tests__/**"]
  "format": "po",
  "extractBabelOptions": {
    "presets": ["babel-preset-gatsby"]

You can find all options in Lingui’s documentation. Make sure that the localeDir is identical with the same option in the theme.

  1. Add three scripts to your package.jsonfile:
  "scripts": {
    "extract": "lingui extract",
    "compile": "lingui compile"


Use Lingui’s scripts to extract messages and compile those to messages.js files. The theme will leverage those compiled files, so make sure that you did those steps before using the theme. The localeDir option must be aligned with the catalogs option of Lingui’s config option.

You can also see an official example to learn more.

Theme options

Key Default Value Description
localeDir none The directory where you’ll store the Lingui files
© 2023 Gatsby, Inc.