gatsby-plugin-i18n
gatsby-plugin-i18n copied to clipboard
Multi language routes for Gatsby
gatsby-plugin-i18n
Hi Folks!
Are you trying to build a multi language gatsby website?
We want to help you! Please open an issue for help, suggestions or bugs.
You can use this plugin with react-intl, i18next, or any other i18n library. This plugin do not translate messages, it just creates routes for each language, and you can use different layouts for each language if you want to.
How it works
Name your files with .langKey.js and the url will be /langKey/path/fileName
Examples:
file | url |
---|---|
src/pages/about.en.js | /en/about |
src/pages/about/index.en.js | /en/about |
src/pages/blog/gatsby-i18n.pt.md | /pt/blog/gatsby-i18n |
Why?
Google! Google needs different URLs to crawl and render your pages for each language.
Showcase
Websites built with Gatsby i18n:
- hugomagalhaes.com (source) Gatsby v2
- angeloocana.com (source)
- tic-tac-toe-ai.surge.sh (source)
- Imagine Clarity
- Peintagone
Feel free to add your project to the list, we would love to see what you are building!
Starters
-
gatsby-starter-default-i18n DEMO, features:
- automatic browser-language detection and redirection
- integration with react-intl
FormattedMessage
with translation keys - custom layout and pages per language
- language switcher component - dev mode with HMR
- build deployed to Netlify
Packages
Install
yarn add gatsby-plugin-i18n
How to use
Include the plugin in your gatsby-config.js
file.
Simple configuration example:
// Add to gatsby-config.js
plugins: [
{
resolve: 'gatsby-plugin-i18n',
options: {
langKeyDefault: 'en',
useLangKeyLayout: false
}
}
]
Blog using markdownRemark configuration example:
// Add to gatsby-config.js
plugins: [
{
resolve: 'gatsby-plugin-i18n',
options: {
langKeyDefault: 'en',
useLangKeyLayout: false,
markdownRemark: {
postPage: 'src/templates/blog-post.js',
query: `
{
allMarkdownRemark {
edges {
node {
fields {
slug,
langKey
}
}
}
}
}
`
}
}
}
]
All Options
-
langKeyDefault: langKey to use when no langKey specified.
-
useLangKeyLayout:
true: use a different layout for each langKey (src/layouts/en.js, src/layouts/pt.js, ...)
false: use default layout (src/layouts/index.js)
-
markdownRemark:
Add markdownRemark if you are using gatsby-transformer-remark.
You can set a postPage component and a query to get the pages.
-
langKeyForNull: langKey added to page context and graphql when no langKey specified. Default: any.
-
pagesPaths: If you are not using just
/src/pages/
folder, you can add an array with the folders your are using:plugins: [ //... other plugins { resolve: 'gatsby-plugin-i18n', options: { //.. other options pagesPaths: [ '/my/custom/pages/folder1', /my/custom/pages/folder2/ ] } } ]
-
prefixDefault:
true: add langKey on all pages, including default
false: omit langKey in url when page lang is the default. Ex: when
langKeyDefault
isen
,blog/first-post.en.md
andblog/first-post.pt.md
will have the following urls:-
/blog/first-post
-
/pt/blog/first-post
Default: true
-
Finally
Go Gatsby!
Go Open-source!
Good luck folks! Open an issue if you need help.