gatsby-theme-i18n

A Gatsby theme for providing internationalization support to your Gatsby site by taking in a configuration file and creating prefixed, enriched pages for each language (including client-only pages that have a matchPath). Also adds tags to your, exposes useful React components and hooks.

Installation

1. Install gatsby-theme-i18n:

   npm install gatsby-theme-i18n gatsby-plugin-react-helmet react-helmet
   

2. Add the configuration to your gatsby-config.js file:

   module.exports = {
     plugins: [
       {
         resolve: `gatsby-theme-i18n`,
         options: {
           defaultLang: `en`,
           configPath: require.resolve(`./i18n/config.json`),
         },
       },
     ],
   }
   

3. Create the folder i18n at the root of your project and create a file called config.json in it.

4. Add your locales to the config file and fill out this information:

   • code: The ISO 3166-1 alpha-2 code which will be used for the path prefix, as a unique identifier (e.g. for the defaultLang option)
   • hrefLang: The IETF language tag for the `` attribute. Also used for og tags
   • name: The english name of the locale
   • localName: The local name of the locale
   • langDir: The direction of language (e.g. "ltr", "rtl")
   • dateFormat: The tokens that Moment.js accepts for date formatting. This can be used for dates on GraphQL queries

   Example config of English and German:

   [
     {
       "code": "en",
       "hrefLang": "en-US",
       "name": "English",
       "localName": "English",
       "langDir": "ltr",
       "dateFormat": "MM/DD/YYYY"
     },
     {
       "code": "de",
       "hrefLang": "de-DE",
       "name": "German",
       "localName": "Deutsch",
       "langDir": "ltr",
       "dateFormat": "DD.MM.YYYY"
     }
   ]
   

5. Add a suffix/postfix to your MDX filenames, e.g. if you have your blogposts at content/posts/my-title/index.mdx you'll need to copy that file and place it with index.de.mdx in the same folder.

Usage

By adding a suffix/postfix in your filenames you can define the locale that the document is in.

You can also see an official example to learn more.

Theme options

You can pass additional options in as they'll be forwarded to the plugin. You can query all options in GraphQL on the themeI18N type.

Available React components/hooks

The theme also exports a couple of components and hooks that you could use in your project.

useLocalization

The theme saves its information into a custom themeI18N graphql type which you can access via the useLocalization hook. Furthermore, you're able to ask for the current locale via React context.

Example:

import * as React from "react"
import { useLocalization } from "gatsby-theme-i18n"

const Example = () => {
  const { locale, config, defaultLang } = useLocalization()

  return (
    <div>
      <div>Current locale: {locale}</div>
      <div>Current defaultLang: {defaultLang}</div>
      <pre>{JSON.stringify(config, null, 2)}</pre>
    </div>
  )
}

export default Example

LocalesList

You can display all available locales via the localesList component.

Example:

import * as React from "react"
import { LocalesList } from "gatsby-theme-i18n"

const Example = () => {
  return (
    <div>
      
    </div>
  )
}

export default Example

LocalizedLink

This is a wrapper around the Link component from gatsby and is transforming links to the correct path by accessing the current locale via React context.

Example:

import * as React from "react"
import { LocalizedLink as Link } from "gatsby-theme-i18n"

const Example = () => {
  return (
    <div>
      Link to second page
    </div>
  )
}

export default Example

LocalizedRouter

Provides a `` from @reach/router that prefixes the basePath prop with the current locale.

Example:

import * as React from "react"
import { LocalizedRouter } from "gatsby-theme-i18n"
import Detail from "../components/detail"

const App = () => {
  return (
    
      
    
  )
}

export default App

MdxLink

This is a component specifically for MDX to replace the normal anchor tag. This way local links to other files are automatically localized (as it uses LocalizedLink behind the scenes).

Example:

import * as React from "react"
import { MDXProvider } from "@mdx-js/react"
import { MdxLink } from "gatsby-theme-i18n"

const components = {
  a: MdxLink,
}

const Layout = ({ children }) => {
  return (
    
      <main>
        {children}
      </main>
    
  )
}

export default Layout

LocaleContext / LocaleProvider

You can also directly access the LocaleContext and LocaleProvider from the theme.

Example:

import * as React from "react"
import { LocaleContext } from "gatsby-theme-i18n"

const Example = () => {
  const locale = React.useContext(LocaleContext)

  return <div>Locale: {locale}</div>
}

export default Example