❤
npm
Sign UpSign In

@ericcote/gatsby-theme-i18n
TypeScript icon, indicating that this package has built-in type declarations

4.1.13 • Public • Published

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 <link rel="alternate" /> tags to your <head>, exposes useful React components and hooks.

Installation

  1. Install gatsby-theme-i18n:

    npm install @ericcote/gatsby-theme-i18n gatsby-plugin-react-helmet react-helmet

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

    module.exports = {
  plugins: [
    {
      resolve: `@ericcote/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 <html lang="xx-XX" /> 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

Key Default Value Description
defaultLang en The locale that is your default language. For this language no prefixed routes will be created unless you set the option prefixDefault.
prefixDefault false All routes will be prefixed, including the defaultLang
configPath none Path to the config file
locales null A string of locales (divided by spaces) to only build a subset of the locales defined in configPath, e.g. en de

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 "@ericcote/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 "@ericcote/gatsby-theme-i18n"

const Example = () => {
  return (
    <div>
      <LocalesList />
    </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 "@ericcote/gatsby-theme-i18n"

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

export default Example

LocalizedRouter

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

Example:

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

const App = () => {
  return (
    <LocalizedRouter basePath="/app">
      <Detail path="/:id" />
    </LocalizedRouter>
  )
}

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 "@ericcote/gatsby-theme-i18n"

const components = {
  a: MdxLink,
}

const Layout = ({ children }) => {
  return (
    <React.Fragment>
      <main>
        <MDXProvider components={components}>{children}</MDXProvider>
      </main>
    </React.Fragment>
  )
}

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 "@ericcote/gatsby-theme-i18n"

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

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

export default Example

Readme

Keywords

Package Sidebar

Install

npm i @ericcote/gatsby-theme-i18n

Repository

github.com/ericcote/themes

Homepage

github.com/ericcote/themes/tree/master/packages/gatsby-theme-i18n#readme

Weekly Downloads

0

Version

4.1.13

License

MIT

Unpacked Size

325 kB

Total Files

21

Last publish

Collaborators

  • ericcote
Try on RunKit
Report malware