Welcome to your new Gatsby site.

Now go build something great.

300px, marginBottom: 1.45rem}}>



export const query = graphql
query ($language: String!) {
locales: allLocale(filter: {language: {eq: $language}}) {
edges {
node {
ns
data
language
}
}
}
}
;
`

and in locales/en/translations.json you will have

`json
{
"Home": "Home",
"Hi people": "Hi people",
"Welcome to your new Gatsby site.": "Welcome to your new Gatsby site.",
"Now go build something great.": "Now go build something great.",
"Go to page 2": "Go to page 2"
}
`

This example is not using semantic keys instead the entire message will be used as a key. Read more.

$3

gatsby-plugin-react-i18next exposes useI18next hook

`javascript
import {Link, useI18next} from 'gatsby-plugin-react-i18next';
import React from 'react';

const Header = ({siteTitle}) => {
const {languages, changeLanguage} = useI18next();
return (


Or a more SEO friendly version using Link component

`javascript
import {Link, useI18next} from 'gatsby-plugin-react-i18next';
import PropTypes from 'prop-types';
import React from 'react';

const Header = ({siteTitle}) => {
const {languages, originalPath} = useI18next();
return (


| Option | Type | Description |
| --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| localeJsonSourceName | string | name of JSON translation file nodes that are loaded by gatsby-source-filesystem (set by option.name). Default is locale |
| localeJsonNodeName | string | name of GraphQL node that holds locale data. Default is locales |
| languages | string[] | supported language keys |
| defaultLanguage | string | default language when visiting /page instead of /es/page |
| fallbackLanguage | string | optionally fallback to a different language than the defaultLanguage |
| generateDefaultLanguagePage | boolean | generate dedicated page for default language. e.g) /en/page. It is useful when you need page urls for all languages. For example, server-side redirect using Accept-Language header. Default is false. |
| redirect | boolean | if the value is true, / or /page-2 will be redirected to the user's preferred language router. e.g) /es or /es/page-2. Otherwise, the pages will render defaultLangugage language. Default is true |
| siteUrl | string | public site url, is used to generate language specific meta tags |
| pages | array | an array of page options used to modify plugin behaviour for specific pages |
| i18nextOptions | object | i18next configuration options |
| verbose | boolean | Verbose output. Default is true |

Page options

| Option | Type | Description |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| matchPath | string | a path pattern like /:lang?/blog/:uid, check path-to-regexp for more info |
| getLanguageFromPath | boolean | if set to true the language will be taken from the :lang param in the path instead of automatically generating a new page for each language |
| excludeLanguages | array | an array of languages to exclude, if specified the plugin will not automatically generate pages for those languages, this option can be used to replace pages in some languages with custom ones |
| languages | array | an array of languages, if specified the plugin will automatically generate pages only for those languages |

Plugin API

$3

Link component is identical to Gatsby Link component except that you can provide additional language prop to create a link to a page with different language

`javascript
import {Link} from 'gatsby-plugin-react-i18next';

const SpanishAboutLink = () => (

About page in Spanish

);
`

$3

Use this react context to access language information about the page

`javascript
const context = React.useContext(I18nextContext);
`

Content of the context object

| Attribute | Type | Description |
| --------------- | -------- | -------------------------------------------------------- |
| language | string | current language |
| languages | string[] | supported language keys |
| routed | boolean | if false it means that the page is in default language |
| defaultLanguage | string | default language provided in plugin options |
| originalPath | string | page path in default language |
| path | string | page path |
| siteUrl | string | public site url provided in plugin options |

The same context will be also available in the Gatsby pageContext.i18n object

$3

This react hook returns I18nextContext, object and additional helper functions

| Function | Description |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| navigate | This is a wrapper around Gatsby navigate helper function that will navigate to the page in selected language |
| changeLanguage | A helper function to change language. The first parameter is a language code. Signature: (language: string, to?: string, options?: NavigateOptions) => Promise. You can pass additional parameters to navigate to different page. |

useI18next also exposes the output of react i18next useTranslation so you can use

`javascript
const {t} = useI18next();
`

How to exclude pages that already have language key in path

For example if you have some other plugin or script that generates your blog posts from headless CRM like prismic.io in different languages you would like to exclude those pages, to not generate duplicates for each language key. You can do that by providing pages option.

`js
pages: [
{
matchPath: '/:lang?/blog/:uid',
getLanguageFromPath: true,
excludeLanguages: ['es']
}
];
`

You have to specify a :lang url param, so the plugin knows what part of the path should be treated as language key.
In this example the plugin will automatically generate language pages for all languages except es. Assuming that you have ['en', 'es', 'de'] languages the blog post with the path /blog/hello-world you will have the following pages generated:

- /blog/hello-world - the English version (if you have en as a defaultLanguage)
- /es/blog/hello-world - the Spanish version that should exist before you run the plugin (created manually or at build time with a plugin or api call)
- /de/blog/hello-world - the German version that is generated automatically

Omit excludeLanguages to get all the languages form the path. Make sure that you have pages for all the languages that you specify in the plugin, otherwise you might have broken links.

You may also need to add a pages config for the 404 page, if it uses the same path pattern as your excluded pages. Note that the order of these rules is important.

`js
pages: [
{
matchPath: '/:lang?/404',
getLanguageFromPath: false
},
{
matchPath: '/:lang?/:uid',
getLanguageFromPath: true,
excludeLanguages: ['es']
}
];
`

How to exclude a page that should not be translated

You can limit the languages used to generate versions of a specific page, for example to limit /preview page to only English version:

`js
pages: [
{
matchPath: '/preview',
languages: ['en']
}
];
`

How to fetch translations of specific namespaces only

You can use ns and language field in gatsby page queries to fetch specific namespaces that are being used in the page. This will be useful when you have several big pages with lots of translations.

`javascript
export const query = graphql
query ($language: String!) {
locales: allLocale(filter: {ns: {in: ["common", "index"]}, language: {eq: $language}}) {
edges {
node {
ns
data
language
}
}
}
}
;
`

Note that in this case only files common.json and index.json will be loaded.
This plugin will automatically add all loaded namespaces as fallback namespaces so if you don't specify a namespace in your translations they will still work.

How to fetch language specific data

You can use language variable in gatsby page queries to fetch additional data for each language. For example if you're using gatsby-transformer-json your query might look like:

`javascript
export const query = graphql
query ($language: String!) {
dataJson(language: {eq: $language}) {
...DataFragment
}
}
;
`

How to add sitemap.xml for all language specific pages

You can use gatsby-plugin-sitemap to automatically generate a sitemap during build time. You need to customize query to fetch only original pages and then serialize data to build a sitemap. Here is an example:

`javascript
// In your gatsby-config.js
plugins: [
{
resolve: 'gatsby-plugin-sitemap',
options: {
excludes: ['//404', '//404.html'],
query:
{
site {
siteMetadata {
siteUrl
}
}
allSitePage(filter: {context: {i18n: {routed: {eq: false}}}}) {
edges {
node {
context {
i18n {
defaultLanguage
languages
originalPath
}
}
path
}
}
}
}
,
serialize: ({site, allSitePage}) => {
return allSitePage.edges.map((edge) => {
const {languages, originalPath, defaultLanguage} = edge.node.context.i18n;
const {siteUrl} = site.siteMetadata;
const url = siteUrl + originalPath;
const links = [
{lang: defaultLanguage, url},
{lang: 'x-default', url}
];
languages.forEach((lang) => {
if (lang === defaultLanguage) return;
links.push({lang, url: ${siteUrl}/${lang}${originalPath}});
});
return {
url,
changefreq: 'daily',
priority: originalPath === '/' ? 1.0 : 0.7,
links
};
});
}
}
}
];
`

How to use a fallback language with semantic keys (vs. message strings)

By default this plugin is setup to fallback on the entire message string, that is used as language key.

In order to use semantic keys, so the fallback message string is the default's language value (instead of the key), it is possible to do the following;

In /gatsby-config.js, setup the plugin as usual, and add the key options.i18nextOptions.fallbackLng (i18next documentation, configuration options, and fallback options);

`
{
resolve: gatsby-plugin-react-i18next,
options: {
localeJsonSourceName: locale,
languages: [en, de, fr],
defaultLanguage: en,
siteUrl: https://example.com/,
i18nextOptions: {
fallbackLng: 'en', // here we provide the fallback language to i18next
interpolation: {
escapeValue: false
},
keySeparator: false,
nsSeparator: false
}
}
}
`

Then in a page query, we avoid to specify a $language variable used as filter, so i18next gets access to the available locales, used as fallback.

`
// /pages/index.js
export const query = graphql
query { // no $language variable defined, no filters on allLocale
locales: allLocale {
edges {
node {
ns
data
language
}
}
}
}
;
`

How to extract translations from pages

You can use babel-plugin-i18next-extract automatically extract translations inside t function and Trans component from you pages and save them in JSON.

1. Install

`
yarn add @babel/cli @babel/plugin-transform-typescript babel-plugin-i18next-extract -D
`

2. create babel-extract.config.js file (don't name it babel.config.js, or it will be used by gatsby)

`javascript
module.exports = {
presets: ['babel-preset-gatsby'],
plugins: [
[
'i18next-extract',
{
keySeparator: null,
nsSeparator: null,
keyAsDefaultValue: ['en'],
useI18nextDefaultValue: ['en'],
discardOldKeys: true,
outputPath: 'locales/{{locale}}/{{ns}}.json',
customTransComponents: [['gatsby-plugin-react-i18next', 'Trans']]
}
]
],
overrides: [
{
test: [/.ts, /.tsx],
plugins: [[@babel/plugin-transform-typescript, {isTSX: true}]]
}
]
};
`

3. add a script to your package.json

`json
{
"scripts": {
"extract": "yarn run babel --config-file ./babel-extract.config.js -o tmp/chunk.js 'src/*/.{js,jsx,ts,tsx}' && rm -rf tmp"
}
}
`

If you want to extract translations per page, you can add a special comment at the beginning of the page:

`
// i18next-extract-mark-ns-start about-page
`

This will create a file about-page.json with all the translations on this page.

To load this file you need to specify a namespace like this:

`javascript
export const query = graphql
query ($language: String!) {
locales: allLocale(
filter: {ns: {in: ["translation", "about-page"]}, language: {eq: $language}}
) {
edges {
node {
ns
data
language
}
}
}
}
;
`

$3

After your messages had been extracted you can use AWS Translate to automatically translate messages to different languages.

This functionality is out of the scope of this plugin, but you can get the idea from this script.

How to fallback to a different language than the defaultLanguage

By default, on first load, this plugin will fallback to the defaultLanguage if the browser's detected language is not included in the array of languages.

If you want to fallback to a different language in the languages array, you can set the fallbackLanguage option.

For example, if the default language of your site is Japanese, you only have English as another language, and you want all other browser-detected languages to fallback to English, not Japanese.

`javascript
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-react-i18next',
options: {
defaultLanguage: 'ja',
fallbackLanguage: 'en'
}
}
]
};
``

Mentions

- Best internationalization for Gatsby by
Adriano Raiano

Credits

This package is based on:

- gatsby-plugin-intl by Daewoong Moon
- gatsby-i18n-plugin by ikhudo

License

MIT © microapps