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
orpages/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)
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