gatsby-plugin-intl

gatsby-plugin-intl is an open-source Gatsby plugin that adds a complete internationalization framework to any Gatsby site, generating per-language static URLs and powered by react-intl for message formatting. It was created by Daewoong Moon (wiziple) and is distributed under the MIT License.

What is gatsby-plugin-intl?

gatsby-plugin-intl is a Gatsby plugin that internationalizes a site by generating static pages for every supported language from a single page component. It takes language JSON resource files (for example src/intl/en.json) as input and outputs routes like /en, /ko, and /de for each page. It runs inside the Gatsby build process and is built on top of react-intl for component APIs and browser-lang for automatic browser-language detection.

Key Features

• Automatic redirection — Uses browser-lang to detect the visitor's preferred language and redirects the root path (/) to the matching locale route (for example, /ko) when the redirect option is set to true.
• One page component for all locales — You write src/pages/index.js once and the plugin creates separate static pages for each language, so you don't need files like pages/en/index.js or pages/ko/index.js.
• react-intl integration — Re-exports FormattedMessage, injectIntl, useIntl, and other react-intl APIs directly from gatsby-plugin-intl, letting you use ICU message syntax for translations.
• Locale-aware Link and navigate — Wraps Gatsby's Link component and navigate function so all internal links automatically keep the current language prefix (for example, linking from /de/page-2 stays under /de).
• changeLocale helper — A function that switches the current locale programmatically: call changeLocale('en', '/page-2') to go from Korean to English on a specific route.
• Configurable options — In gatsby-config.js you set the language resource path, the languages array, the defaultLanguage, a redirect boolean, and an optional redirectComponent for SEO content on redirect pages.
• Production-proven — The README showcases sites using this plugin, including ethereum.org, picpick.app, and neonlaw.com, plus a demo starter named gatsby-starter-default-intl.

Who is it for?

• Gatsby developers who build multilingual websites and want to handle i18n without maintaining separate page files per language.
• SEO-focused site owners who need distinct URLs for each language version of their content, following Google's guidelines for multilingual sites.
• Open-source maintainers who want a plug-in i18n solution that can be extended with their own language JSON resources and locale configuration.

What can you do with gatsby-plugin-intl?

• Add i18n to an existing Gatsby site — Install the plugin, add language JSON files, and wrap your components with injectIntl or the useIntl hook to translate UI strings.
• Build a language switcher — Use the locale-aware Link or the changeLocale function to let visitors switch between /en, /ko, or /de versions of the same page.
• Serve fully static localized pages — During gatsby build, the plugin emits static HTML for every language route, so no client-side rendering is required for the translated content.
• Create localized URLs for SEO — Each language version gets its own URL path (e.g., /de/page-2), which you can use with hreflang tags and language-specific sitemaps.

How does gatsby-plugin-intl work?

During the Gatsby build, the plugin reads the language JSON files you specify and creates a static page for every locale for each page in your pages directory. For example, src/pages/index.js is generated as /en, /ko, /de, and optionally /; src/pages/page-2.js becomes /en/page-2, /ko/page-2, and /de/page-2. When redirect is true, the default locale-less URLs redirect to the visitor's preferred language; otherwise they render in the defaultLanguage.

Pricing

gatsby-plugin-intl is free and open source, released under the MIT License, so you can use it in commercial and personal projects at no cost.

FAQ

Is gatsby-plugin-intl free?

Yes, gatsby-plugin-intl is open source under the MIT License. You can use it in any project, including commercial ones, without paying a license fee.

What languages does gatsby-plugin-intl support?

The plugin supports any language you define through JSON resource files, with no hard-coded limit. The README's example configures English, Korean, and German using en.json, ko.json, and de.json.

Does gatsby-plugin-intl require a separate page file for each language?

No. You write one page component (such as src/pages/index.js), and the plugin generates a static page for every language during the Gatsby build, creating URLs like /en and /ko.

How do I switch languages with gatsby-plugin-intl?

You can use the wrapped Link component for declarative navigation, the navigate function for imperative navigation, or the changeLocale function to change locale programmatically, for example changeLocale('en', '/page-2').

What is the redirectComponent option for?

It is an optional string pointing to a component file that the plugin renders alongside the redirection component. This is useful for adding SEO or analytics content to the default redirect page.