Gridsome i18n plugin

A i18n plugin for Gridsome.

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

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

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>

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.