Gatsby I18n Plugin 🌐, which let you translate pages, content and the url or slugs of pages. Batteries 🔋 included.
MIT License
Providing i18n and l10n to Gatsby. Besides translating pages and Markdown files, you can also translate the slugs and paths and still link between translated sibling pages. Batteries like a language switcher component are included. The plugin is written in Typescript, has some tests and has only one peer dependency:
src/pages/about.tsx
and the languages en-US
and de-CH
configured, then it will create an en-US
and de-CH
version of this page. Via the page context of the translated pages, you get to know the locale.gatsby-transformer-remark
and gatsby-plugin-mdx
.<LocalizedLink>
and <LanguageSwitcher>
.Make sure the packages "gatsby": "^5.x"
and "react-intl": "^6.x"
are dependencies of your Gatsby project.
Install the plugin with npm install gatsby-plugin-i18n-l10n
or yarn add gatsby-plugin-i18n-l10n
.
Load and configure the plugin from your gatsby-config.js
or gatsby-config.ts
:
{
resolve: `gatsby-plugin-i18n-l10n`,
options: {
// string: IETF BCP 47 language tag: default locale, which won't be prefixed
defaultLocale: `de-CH`,
// string: absolute site url
siteUrl: `https://example.com`,
// locales[]: all locales, which should be available
locales: [
{
// string: IETF BCP 47 language tag of this language
locale: `en-US`,
// string: prefix for this language, which will be used to prefix the url, if it's not the default locale
prefix: `en`,
// object: mapping of given urls (by filename) to translated urls, if no mapping exists, given url will be used
slugs: {},
// object: this messages will be handed over to react-intl and available throughout the website
messages: {
"language": "English"
},
},
// another language
{
locale: `de-CH`,
prefix: `de`,
slugs: {
'/products/': '/produkte/',
'/products/#donut-filled-with-jam': '/produkte/#berliner',
'/services/software-development/': '/dienstleistungen/softwareentwicklung/'
},
pageBlacklist: ['/do-not-translate-to-german/'], // If there is a page with the a given path it won't be translated
messages: {
"language": "Deutsch"
},
},
],
// omit certain path segments (relative directories)
// be careful not to cause path collisions
pathBlacklist: [
'/pages' // /pages/products/gummibears/ becomes /products/gummibears/
],
// set handling of trailing slashes
// set it to the same value as for the rest of Gatsby
// behaves like https://www.gatsbyjs.com/docs/reference/config-files/gatsby-config/#trailingslash
// default: always
trailingSlash: 'always'
},
}
<LanguageSwitcher>
With the built-in <LanguageSwitcher>
component users can change between the locales. With resolveLanguageName
prop the language names can be provided to the component.
<LanguageSwitcher resolveLanguageName={(locale) => intl.formatMessage({ id: `languages.${locale}` })} />
<LocalizedLink>
<LocalizedLink>
wraps Gatsby <Link>
component, thus it should be possible to use it in the same way.
<LocalizedLink to="/products/">Produkte</LocalizedLink>
If the configuration from above is used and the user views this link inside the i18n context de-CH
the link will lead him to /de/produkte
.
<GenericLocalizedLink>
With the built-in <GenericLocalizedLink>
component it's possible to use other plugins, which modify Gatsbys <Link>
component. Here is an example with Gatsby Plugin Transition Link:
<GenericLocalizedLink to="/imprint/">
{(args) => (
<TransitionLink
to={args.to}
exit={{
trigger: ({ exit, node }) => this.interestingExitAnimation(exit, node),
length: 1,
}}
entry={{
delay: 0.6,
}}
>
Go to page 2
</TransitionLink>
)}
</GenericLocalizedLink>
Another example with <AniLink>
:
<GenericLocalizedLink to="/imprint">
{(args) => (
<AniLink fade to={args.to}>
Go to Page 4
</AniLink>
)}
</GenericLocalizedLink>
createPage()
When you create pages programmatically with createPage()
by default the page will only try to set the locale and prefix to the context. With the following options you can instruct the plugin to internationalize the context further:
referTranslations: string[]
: Refers translations for given locales.adjustPath: boolean
: Add locale prefix and replaces slugs.All translation messages are sourced to Gatsbys GraphQL data layer with translation
and allTranslation
. Here is an example GraphQL query:
export const query = graphql`
query SomePage($locale: String) {
pageTitle: translation(locale: { eq: $locale }, key: { eq: "page.some.title" }) {
message
}
pageDescription: translation(locale: { eq: $locale }, key: { eq: "page.some.description" }) {
message
}
}
`;
npm install
.npm test
.npm run example install
.npm run example start
.