Gatsby Book Launch

“The missing guide to the modern web” launches on Thursday, Sep 29th: Modular: The Web’s New Architecture

ContactSign Up for Free
Community Plugin
View plugin on GitHub


Codecov GitHub Workflow Status npm npm

Providing i18n and l10n to Gatsby. Besides translating pages and Markdown files, you can also translate the slugs and paths and still link between translated sibling pages. Batteries like a language switcher component are included. The plugin is written in Typescript, has some tests and builts on these two dependencies:

  • react-intl: Wrapping the pages with a provider, which makes translation available throughout the app.


  • Generates translated versions of pages.
    • For example, if you have a page src/pages/about.tsx and the languages en-US and de-CH configured, then it will create an en-US and de-CH version of this page. Via the page context of the translated pages, you get to know the locale.
  • Adds fields on MarkdownRemark and Mdx nodes.
  • Puts prefixes into the page paths, but not when it’s the default locale.
  • Picks up locale from Markdown file names and provides it via custom fields in GraphQL.
    • It works with gatsby-transformer-remark and gatsby-plugin-mdx.
  • Makes it easy to navigate between the translations of a page.
  • Sets meta tags to provide locale information to crawlers and other machines.
  • Provides useful components like <LocalizedLink> and <LanguageSwitcher>.
  • Helps to translate paths, while keeping the possibility to navigate between the translations of a page.


  1. Make sure the peer dependencies "gatsby": "^4.x" and "react-intl": "^6.x" are dependencies of your Gatsby project.

  2. Install the plugin with npm install gatsby-plugin-i18n-l10n or yarn add gatsby-plugin-i18n-l10n.

  3. Load and configure the plugin from your gatsby-config.js or gatsby-config.ts:

      resolve: `gatsby-plugin-i18n-l10n`,
      options: {
        // IETF BCP 47 language tag: default locale, which won't be prefixed
        defaultLocale: `de-CH`,
        // string: absolute site url
        siteUrl: ``,
        // locales[]: all locales, which should be available
        locales: [
            // IETF BCP 47 language tag of this language
            locale: `en-US`,
            // string: prefix for this language, which will be used to prefix the url, if it's not the default locale
            prefix: `en`,
            // object: mapping of given urls (by filename) to translated urls, if no mapping exists, given url will be used
            slugs: {},
            // object: this messages will be handed over to react-intl and available throughout the website
            messages: {
              "language": "English"
          // another language
            locale: `de-CH`,
            prefix: `de`,
            slugs: {
              '/products': '/produkte',
              '/products#donut-filled-with-jam': '/produkte#berliner',
              '/services/software-development': '/dienstleistungen/softwareentwicklung'
            messages: {
              "language": "Deutsch"
        // omit certain path segments (relative directories)
        // be careful not to cause path collisions
        pathBlacklist: [
          '/pages' // /pages/products/gummibears becomes /products/gummibears


With the built-in <LanguageSwitcher> component, as user can change between the locales. With resolveLanguageName the language names can be provided to the component.

<LanguageSwitcher resolveLanguageName={(locale) => intl.formatMessage({ id: `languages.${locale}` })} />


When you create pages programmatically with createPage() by default the page will only try to set the locale and prefix to the context. With the following options you can instruct the plugin to internationalize the context further:

  • referTranslations: string[]: Refers translations for given locales.
  • adjustPath: boolean: Add locale prefix and replaces slugs.


© 2022 Gatsby, Inc.