gatsby-theme-i18n
v3.0.0
Published
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.
Downloads
2,135
Readme
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
Install
gatsby-theme-i18n:npm install gatsby-theme-i18n gatsby-plugin-react-helmet react-helmetAdd the configuration to your
gatsby-config.jsfile:module.exports = { plugins: [ { resolve: `gatsby-theme-i18n`, options: { defaultLang: `en`, configPath: require.resolve(`./i18n/config.json`), }, }, ], }Create the folder
i18nat the root of your project and create a file calledconfig.jsonin it.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 thedefaultLangoption)hrefLang: The IETF language tag for the<html lang="xx-XX" />attribute. Also used for og tagsname: The english name of the localelocalName: The local name of the localelangDir: 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" } ]Add a suffix/postfix to your MDX filenames, e.g. if you have your blogposts at
content/posts/my-title/index.mdxyou'll need to copy that file and place it withindex.de.mdxin 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 "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 ExampleLocalesList
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>
<LocalesList />
</div>
)
}
export default ExampleLocalizedLink
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="/page-2/">Link to second page</Link>
</div>
)
}
export default ExampleLocalizedRouter
Provides a <Router /> 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 (
<LocalizedRouter basePath="/app">
<Detail path="/:id" />
</LocalizedRouter>
)
}
export default AppMdxLink
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 (
<React.Fragment>
<main>
<MDXProvider components={components}>{children}</MDXProvider>
</main>
</React.Fragment>
)
}
export default LayoutLocaleContext / 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