Gatsby plugin to add react-intl onto a site
npm install @dethtroll/gatsby-plugin-react-intlgatsby-plugin-react-intl has supported gatsby v3! Please upgrade gatsby-plugin-react-intl to ^3.0.0 to use it
gatsby-plugin-react-intl@1.3.0
ignoredPaths: paths that you don't want to genereate locale pages, example: ["/dashboard/","/test/**"], string format is from micromatch https://github.com/micromatch/micromatch
redirectDefaultLanguageToRoot: option for use / as defaultLangauge root path. if your defaultLanguage is ko, when redirectDefaultLanguageToRoot is true, then it will not generate /ko/xxx pages, instead of /xxx
fallbackLanguage: option to fallback to the defined language instead of the defaultLanguage if the user langauge is not in the list
pages/en/index.js or pages/ko/index.js.
npm install --save gatsby-plugin-react-intl
javascript
// In your gatsby-config.js
plugins: [
{
resolve: gatsby-plugin-react-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,
// option for use / as defaultLangauge root path. if your defaultLanguage is ko, when redirectDefaultLanguageToRoot is true, then it will not generate /ko/xxx pages, instead of /xxx
redirectDefaultLanguageToRoot: false,
// paths that you don't want to genereate locale pages, example: ["/dashboard/","/test/**"], string format is from micromatch https://github.com/micromatch/micromatch
ignoredPaths: [],
// option to fallback to the defined language instead of the defaultLanguage if the user langauge is not in the list
fallbackLanguage: en,
},
},
]
`
$3
For example,
| language resource file | language |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------- |
| src/intl/en.json | English |
| src/intl/ko.json | Korean |
| src/intl/de.json | German |
$3
You can use injectIntl HOC on any react components including page components.
`jsx
import React from "react"
import { injectIntl, Link, FormattedMessage } from "gatsby-plugin-react-intl"
const IndexPage = ({ intl }) => {
return (
{intl.formatMessage({ id: "go_page2" })}
{/ OR
)
}
export default injectIntl(IndexPage)
`
Or you can use the new useIntl hook.
`jsx
import React from "react"
import { useIntl, Link, FormattedMessage } from "gatsby-plugin-react-intl"
const IndexPage = () => {
const intl = useIntl()
return (
{intl.formatMessage({ id: "go_page2" })}
{/ OR
)
}
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-react-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)` |