Gatsby Starter Intl is a Gatsby v2 boilerplate starter for multilingual static sites that generates a locale-prefixed page for every language you define and automatically redirects visitors based on their browser language.
What is Gatsby Starter Intl?
Gatsby Starter Intl is a Gatsby v2 starter boilerplate for building multilingual static sites. It takes a set of languages and translation files as input and produces a static site with locale-prefixed paths for every language, such as /en/page-2 and /pl/page-2. The starter is maintained by Tomasz Skuta (tomekskuta) and extends the official Gatsby Starter Default with an internationalization layer built on react-intl.
Key Features
- Automatic locale detection — detects the browser language and redirects root paths to the correct locale route, for example /page-2 redirects to /en/page-2.
- Static pages per language — Gatsby builds separate static HTML files for each language defined in src/i18n/languages.js, which SEO-friendly Google can index.
- React-intl translations — translations are stored per page in src/i18n/translations, using the flat library to convert nested objects to the flat format react-intl requires.
- Layout HOC with Context API — the withLayout higher-order component shares pageContext and customProps through React Context, so pages no longer manually pass locale props to every layout component.
- React 16.8 hooks support — because the starter runs on React 16.8, you can use hooks such as useContext to access the page context in any component.
- Language switcher component — src/components/Langs.jsx saves the chosen locale to localStorage and uses Gatsby's navigate method to redirect to the corresponding locale page.
- Jest unit testing setup — includes example snapshot tests for pages and a Header component test, configured according to the official Gatsby unit testing documentation.
Who is it for?
- React developers who want a preconfigured i18n setup rather than wiring react-intl and locale routing themselves.
- Content sites and blogs that need to serve the same content in multiple languages with clean locale paths like /en/blog and /pl/blog.
- Agencies and freelancers building client websites that require browser-language detection and automatic redirects out of the box.
What can you do with Gatsby Starter Intl?
- Launch a new multilingual site quickly — run gatsby new your-project-name with the starter URL, then edit src/i18n/languages.js and add per-page translation files to support additional languages.
- Customize the layout per locale — pass customProps such as localeKey to withLayout to set per-language site title, description, and keywords for better SEO.
- Handle localized 404 pages — the starter generates a 404 page for every language; if your static host cannot serve them, add a condition in gatsby-node.js to skip localized 404s.
How does it work?
The starter hooks into Gatsby's onCreatePage API in gatsby-node.js to create a route for every language defined in src/i18n/languages.js. A Redirect component wraps each root path without a locale, reading from localStorage or the browser's language list to redirect to the correct locale route. The withLayout HOC then injects pageContext and custom props into each page via React Context, so components can read the current locale without prop drilling.
FAQ
Is Gatsby Starter Intl free?
Yes, it is open source under the MIT license, so you can use it in personal and commercial projects without licensing fees.
What languages does it support?
It is language-agnostic — you list each locale in src/i18n/languages.js with a locale key, a display label, and an optional default flag. The demo site uses English and Polish, but any number of languages can be added.
Does it support React hooks?
Yes, the starter uses React 16.8, so hooks are available. The included PageContext is specifically designed to be read with the useContext hook.
How do I change the language?
The Langs.jsx component writes the selected locale to localStorage and calls Gatsby's navigate method to redirect to the equivalent page in the chosen language.
Can I hide the language switcher?
Yes, the withLayout customProps include hideLangs, which when set to true removes the language-changing options; the starter's 404 page uses this prop.
