gridsome-plugin-i18n v1.6.0
Gridsome i18n plugin
Install
yarn add gridsome-plugin-i18n
npm install gridsome-plugin-i18n --save
Getting Started
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'),
}
}
}
]
};
Options
locales
- Type:
string[]
required
A list of all supported locales.
messages
- Type:
object
Declaration of JSON messages files, for more info check VueI18n's doc.
pathAliases
- Type:
object
A list of locale's path segment to use, if not provided the locale code will be use to generate url.
fallbackLocale
- Type:
string
Language to use when your preferred language lacks a translation, for more info check VueI18n's doc.
defaultLocale
- Type:
string
- Default: first locale
Default locale to use in page's path without locale segment in it.
enablePathRewrite
- Type:
boolean
- Default:
true
Enable automatic rewrite of path for Vue Router.
rewriteDefaultLanguage
- Type:
boolean
- Default:
true
Enable path rewrite for default language.
enablePathGeneration
- Type:
boolean
- Default:
true
Enable translated path automatic generation. Disabling this no additional pages are generated, just include i18n Vue Plugin and let you to manage translated path generation.
routes
- Type:
object
- Default:
{}
Routes to generate using a custom path.
Usage
This plugin will install and configure Vue I18n, so refer to it about usage.
URL generation
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
Route translation
If you want to translate the path of pages for each language, you first need to disable the automatic path generation:
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
locales: [
'it-it',
'en-gb'
],
enablePathGeneration: false // disable path generation
}
}
]
};
now you can manually add your routes declaration for each languages.
It is recommended to use a separate file in order not to enlarge the configuration file, add a file named routes.js
in the root directory of your project:
module.exports = {
en: [
{
path: '/en/',
component: './src/pages/Index.vue'
},
{
path: '/en/about/',
component: './src/pages/About.vue'
}
],
it: [
{
path: '/',
component: './src/pages/Index.vue'
},
{
path: '/it/chi-siamo/',
component: './src/pages/About.vue'
}
]
};
then load this route file into Gridsome configuration file:
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
locales: [
'it-it',
'en-gb'
],
enablePathGeneration: false,
routes: require('./routes.js') // load path translation declaration from external file
}
}
]
};
this plugin will generate pages based on provided configurations.
Route translation using remote routing system
If you have a large project and you manage your page path from data source simply disable path generation:
module.exports = {
plugins: [
{
use: "gridsome-plugin-i18n",
options: {
locales: [
'it-it',
'en-gb'
],
enablePathGeneration: false, // disable path generation
routes: {} // disable path generation
}
}
]
};
set routes
settings as an empty object or directly not set it.
Generate pages from your external source inside your gridsome.server.js
:
module.exports = function (api) {
api.createPages(async ({ createPage, graphql }) => {
// query your data source to retrieve pages
const response = await graphql(`
query {
mysource {
PageItems {
items {
id
name,
path,
slug
}
}
}
}
`)
if (response.errors) {
throw response.errors[0]
}
// generate pages from query response
response.data.mysource.PageItems.items.forEach((page) => {
createPage({
path: page.path || page.slug, // here you can handle page's path
component: './src/templates/DynamicPage.vue',
context: {
id: page.id,
locale: page.locale // set page locale for context variable (used for GraphQL queries)
},
route: {
meta: {
locale: page.locale // set page locale for frontend routing
}
}
})
})
})
}
this give you the complete control of routes path translation and management.
Content translation
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>
Using with page query
You can use context property locale
to filter page queries:
<page-query>
query($locale:String) {
example {
_allDocuments(lang:$locale) {
edges {
node {
title
}
}
}
}
}
</page-query>
your data source need to support query based on locale.
Hot reload
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.
Link routing integration
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)
Locale switcher components
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>
Vue instance helpers
$tp
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.
Use cases
Links and resources for usage with other Gridsome source and plugins
@gridsome/source-filesystem
Refer to this issue's comments to find an example of usage with Gridsome filesystem source plugin: #16