gatsby-starter-i18n-linguijs is a Gatsby starter that pre-configures js-lingui for multilingual static sites, generating one page per locale to avoid duplicating React components and content.
What is gatsby-starter-i18n-linguijs?
gatsby-starter-i18n-linguijs is a Gatsby starter template built around the js-lingui internationalization library. It takes a standard Gatsby site and adds the configuration needed to render the same pages in multiple locales, producing a static set of localized pages. The starter is available as a GitHub repository with a live demo hosted on Netlify, and it runs on the Gatsby static site generator, which means all pages are pre-rendered at build time.
Key Features
- Locale-per-page generation — The starter automatically generates one output page for each locale, so you don't maintain separate code or components per language.
- js-lingui integration — It wires up the js-lingui library (including
@lingui/reactand related packages) to manage message catalogs and translation extraction. - CLI-based workflow — Install
gatsby-cliandjs-linguiglobally, then usenpm run extractto extract translatable strings andnpm run developto run the dev server. - Easy locale addition — Add a new language with a single command:
lingui add-locale ru(for Russian, for example). - Centralized catalog config — Locale catalogs are wired up in
src/i18n-config, giving you one place to manage language setup. - Translated path support — The starter supports localized URLs by letting you map default paths to localized paths in
gatsby-nodeand the locale files. - Demo and inspiration — Includes links to a live demo and to GitHub issues/repositories that inspired the approach (Gatsby issue #3853, js-lingui issue #158, and morloy/ledgy.com).
Who is it for?
This starter is aimed at Gatsby developers who need to ship a multilingual site. It's for teams that want internationalization without building the i18n plumbing from scratch, and for anyone who wants to use js-lingui's extraction workflow rather than manually managing translation files. It's also useful for static site projects that need localized URLs for SEO.
What can you do with it?
- Multilingual content sites: Generate the same blog or marketing pages in English, Russian, or any other locale, each with its own URL.
- Global product landing pages: Localize the UI strings and content using catalog files extracted by js-lingui.
- Documentation sites: Build per-locale documentation pages and update the path mapping in
gatsby-nodeso each language has its own route structure. - Developers evaluating i18n patterns: Use the starter as a reference implementation for combining Gatsby with js-lingui, including translated paths.
How does it work?
The workflow starts with global installation: npm install --global gatsby-cli js-lingui. Next you run npm run extract to scan your source and generate translation catalogs. Add a locale with lingui add-locale ru, configure the catalogs in src/i18n-config, and then npm run develop will serve the site. For translated paths, you edit gatsby-node and the locale files to map each default path to its localized equivalent.
Pros and cons
-
Avoids duplicate code — you write components once and they render in every locale.
-
Mature library — js-lingui is a widely used i18n solution with extraction tooling.
-
Community-driven — the starter credits specific GitHub discussions and repositories that informed its design.
-
Requires global CLIs — you must install
gatsby-cliandjs-linguiglobally for the extract and add-locale commands. -
Manual catalog wiring — after adding a locale, you need to manually update
src/i18n-config. -
Translated paths need manual mapping — there is no automatic URL translation; you have to maintain the mappings yourself.
FAQ
How do I add a new language?
Run lingui add-locale with the locale code (for example lingui add-locale ru for Russian), then wire up the catalog in src/i18n-config as described in the starter's config section.
What does npm run extract do?
It extracts translatable strings from your source code and generates or updates the message catalogs that js-lingui uses for translations. You run it before collecting translations from translators.
Does the starter create separate URLs for each language?
Yes, it generates pages for each locale. If you want custom URL paths (for example /ru/about instead of /about/ru), you need to set up the translated path mapping in gatsby-node and the locale files.
What is js-lingui?
js-lingui is an internationalization library for JavaScript applications. This starter integrates it with Gatsby so that your site can display translated content based on locale.
Do I need to know js-lingui to use this starter?
The starter assumes you understand the basics of js-lingui's message catalog workflow. The README points to the official js-lingui docs for further reference on the library.
