yarn add gridsome-plugin-i18n
npm install gridsome-plugin-i18n --save
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
locales: [ // locales list
'it-it',
'fr-fr',
'de-de',
'en-gb'
],
pathAliases: { // path segment alias for each locales
'it-it': 'it',
'fr-fr': 'fr',
'de-de': 'de',
'en-gb': 'en'
},
fallbackLocale: 'en-gb', // fallback language
defaultLocale: 'en-gb', // default language
enablePathRewrite: true, // rewrite path with locale prefix, default: true
rewriteDefaultLanguage: true, // rewrite default locale, default: true
messages: {
'it-it': require('./src/locales/it-it.json'), // Messages files
'fr-fr': require('./src/locales/fr-fr.json'),
'de-de': require('./src/locales/de-de.json'),
'en-gb': require('./src/locales/en-gb.json'),
}
}
}
]
};
- Type:
string[]
required
A list of all supported locales.
- Type:
object
Declaration of JSON messages files, for more info check VueI18n's doc.
- Type:
object
A list of locale's path segment to use, if not provided the locale code will be use to generate url.
- Type:
string
Language to use when your preferred language lacks a translation, for more info check VueI18n's doc.
- Type:
string
- Default: first locale
Default locale to use in page's path without locale segment in it.
- Type:
boolean
- Default:
true
Enable automatic rewrite of path for Vue Router.
- Type:
boolean
- Default:
true
Enable path rewrite for default language
This plugin will install and configure Vue I18n, so refer to it about usage.
This plugin will load all pages already declared and generate pages for all locales adding a path prefix with the locale code.
For example, if you have these paths:
/ -> component home
/about -> component about
/blog/article1 -> component article
/blog/article2 -> component article
this plugin, with these locales:
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
locales: [
'it-it',
'en-gb'
],
}
}
]
};
will generate these pages:
/ -> component home
/it-it/ -> component home
/en-gb/ -> component home
/en-gb/about -> component about
/it-it/about -> component about
/about -> component about
/it-it/about -> component about
/en-gb/about -> component about
/blog/article1 -> component article
/it-it/blog/article1 -> component article
/en-gb/blog/article1 -> component article
/blog/article2 -> component article
/it-it/blog/article2 -> component article
/en-gb/blog/article2 -> component article
using path aliases:
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
locales: [
'it-it',
'en-gb'
],
pathAliases: {
'it-it': 'it',
'en-gb': 'en'
},
}
}
]
};
will generate these pages:
/ -> component home
/it/ -> component home
/en/ -> component home
/en/about -> component about
/it/about -> component about
/about -> component about
/it/about -> component about
/en/about -> component about
/blog/article1 -> component article
/it/blog/article1 -> component article
/en/blog/article1 -> component article
/blog/article2 -> component article
/it/blog/article2 -> component article
/en/blog/article2 -> component article
This plugin will set a context property to store current locale:
<template>
<span>
Current locale: {{ $context.locale }}
</span>
</template>
Using VueI18n:
<template>
<span>
Current locale: {{ $i18n.locale }}
</span>
</template>
and translate string using $t
helper:
<template>
<span>
{{ $t('my-message') }}
</span>
</template>
You can use context property locale
to filter page queries:
<page-query>
query($locale:String) {
example {
_allDocuments(lang:$locale) {
edges {
node {
title
}
}
}
}
}
</page-query>
When is messages are declared gridsome.config.js
will be read once during Gridsome startup and will not be watched by webpack dev server (being outside ./dist folder).
In order to enable hot reload remove messages from gridsome.config.js
:
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
// ...
messages: {}
}
}
]
};
and load it from main.js
file:
export default function (Vue, { appOptions }) {
// ...
appOptions.i18n.setLocaleMessage('it-it', require('./locales/it-it.json'))
appOptions.i18n.setLocaleMessage('fr-fr': require('./locales/fr-fr.json'))
appOptions.i18n.setLocaleMessage('de-de': require('./locales/de-de.json'))
appOptions.i18n.setLocaleMessage('en-gb': require('./locales/en-gb.json'))
}
this will use i18n setLocaleMessage API to load message from client side. Now messages files are included in webpack bundle and a file change will trigger a page reload having a better development experience.
This plugin will add an additional logic to Vue Router when resolving paths, for example is you are using a link like this:
<g-link to="/projects/">Projects</g-link>
the resolved route will be found checking for current locale set and add the appropriate path prefix like /en/projects/
.
It's possible to disable this feature and manage routing on your own:
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
enablePathRewrite: false
}
}
]
};
then you have to properly add path prefix:
<g-link :to="$tp('/projects/')">Projects</g-link>
(read more about $tp
helper in next section)
Here an example of a Vue component to switch locale, creating into ./src/components/LocaleSwitcher.vue
:
<template>
<select v-model="currentLocale" @change="localeChanged">
<option v-for="locale in availableLocales" :key="locale" :value="locale">{{ locale }}</option>
</select>
</template>
<script>
export default {
name: "LocaleSwitcher",
data: function () {
return {
currentLocale: this.$i18n.locale.toString(),
availableLocales: this.$i18n.availableLocales
}
},
methods: {
localeChanged () {
this.$router.push({
path: this.$tp(this.$route.path, this.currentLocale, true)
})
}
}
}
</script>
Is a function that accept a path as arguments and return a localized prefixed path version.
// this.$i18n.locale is "en-gp"
const localizedPath = this.$tp('/projects/')
// localizedPath is "/en/projects/"
If a localized path prefix is already set it will returns the same path:
// this.$i18n.locale is "en-gp"
const localizedPath = this.$tp('/it/projects/')
// localizedPath is "/it/projects/"
this in order to not create redirect loop.
This is useful for render a correct path for builded <g-link>
directives:
<g-link :to="$tp('/projects/')">Projects</g-link>
after build become:
<a href="/en/projects/">Projects</a>
It's also possible to select which locale to use during translation passing to second string parameter:
const localizedPath = this.$tp('/projects/', 'fr-fr')
// localizedPath is "/fr/projects/"
this will not works when path is already translated:
const localizedPath = this.$tp('/it/projects/', 'fr-fr')
// localizedPath is "/it/projects/" <--- not changed
To force changing locale add a third boolean parameter:
const localizedPath = this.$tp('/it/projects/', 'fr-fr', true)
// localizedPath is "/fr/projects/"
useful to language selector implementation.