gatsby-plugin-intl

Internationalize your Gatsby site.

Features

• Turn your gatsby site into an internationalization-framework out of the box powered by react-intl.

• Support automatic redirection based on the user's preferred language in browser provided by browser-lang.

• Support multi-language url routes in a single page component. This means you don't have to create separate pages such as pages/en/index.js or pages/ko/index.js.

Why?

When you build multilingual sites, Google recommends using different URLs for each language version of a page rather than using cookies or browser settings to adjust the content language on the page. (read more)

Starters

Demo: http://gatsby-starter-default-intl.netlify.com

Source: https://github.com/wiziple/gatsby-plugin-intl/tree/master/examples/gatsby-starter-default-intl

Showcase

• https://picpick.app
• https://www.krashna.nl (Source)
• https://vaktija.eu
• https://anhek.dev (Source)
• https://pkhctech.ineo.vn (Source)
• https://www.neonlaw.com (Source)
• https://ethereum.org (Source)
• https://marscollective.co (Source)

Feel free to send us PR to add your project.

How to use

Install package

npm install --save gatsby-plugin-intl

Add a plugin to your gatsby-config.js

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-intl`,
    options: {
      // language JSON resource path
      path: `${__dirname}/src/intl`,
      // supported language
      languages: [`en`, `ko`, `de`],
      // language file path
      defaultLanguage: `ko`,
      // option to redirect to `/ko` when connecting `/`
      redirect: true,
    },
  },
]

You'll also need to add language JSON resources to the project.

For example,

| language resource file | language | | --- | --- | | src/intl/en.json | English | | src/intl/ko.json | Korean | | src/intl/de.json | German |

Change your components

You can use injectIntl HOC on any react components including page components.

import React from "react"
import { injectIntl, Link, FormattedMessage } from "gatsby-plugin-intl"

const IndexPage = ({ intl }) => {
  return (
    <Layout>
      <SEO
        title={intl.formatMessage({ id: "title" })}
      />
      <Link to="/page-2/">
        {intl.formatMessage({ id: "go_page2" })}
        {/* OR <FormattedMessage id="go_page2" /> */}
      </Link>
    </Layout>
  )
}
export default injectIntl(IndexPage)

Or you can use the new useIntl hook.

import React from "react"
import { useIntl, Link, FormattedMessage } from "gatsby-plugin-intl"

const IndexPage = () => {
  const intl = useIntl()
  return (
    <Layout>
      <SEO
        title={intl.formatMessage({ id: "title" })}
      />
      <Link to="/page-2/">
        {intl.formatMessage({ id: "go_page2" })}
        {/* OR <FormattedMessage id="go_page2" /> */}
      </Link>
    </Layout>
  )
}
export default IndexPage

How It Works

Let's say you have two pages (index.js and page-2.js) in your pages directory. The plugin will create static pages for every language.

file | English | Korean | German | Default* -- | -- | -- | -- | -- src/pages/index.js | /en | /ko | /de | / src/pages/page-2.js | /en/page-2 | /ko/page-2 | /de/page-2 | /page-2

Default Pages and Redirection

If redirect option is true, / or /page-2 will be redirected to the user's preferred language router. e.g) /ko or /ko/page-2. Otherwise, the pages will render defaultLangugage language. You can also specify additional component to be rendered on redirection page by adding redirectComponent option.

Plugin Options

Option | Type | Description -- | -- | -- path | string | language JSON resource path languages | string[] | supported language keys defaultLanguage | string | default language when visiting /page instead of ko/page redirect | boolean | if the value is true, / or /page-2 will be redirected to the user's preferred language router. e.g) /ko or /ko/page-2. Otherwise, the pages will render defaultLangugage language. redirectComponent | string (optional) | additional component file path to be rendered on with a redirection component for SEO.

Components

To make it easy to handle i18n with multi-language url routes, the plugin provides several components.

To use it, simply import it from gatsby-plugin-intl.

Component | Type | Description -- | -- | -- Link | component | This is a wrapper around @gatsby’s Link component that adds useful enhancements for multi-language routes. All props are passed through to @gatsby’s Link component. navigate | function | This is a wrapper around @gatsby’s navigate function that adds useful enhancements for multi-language routes. All options are passed through to @gatsby’s navigate function. changeLocale | function | A function that replaces your locale. changeLocale(locale, to = null) IntlContextConsumer | component | A context component to get plugin configuration on the component level. injectIntl | component | https://github.com/yahoo/react-intl/wiki/API#injection-api FormattedMessage | component | https://github.com/yahoo/react-intl/wiki/Components#string-formatting-components and more... | | https://github.com/yahoo/react-intl/wiki/Components

License

MIT © Daewoong Moon