Pitcher JavaScript Platform

# Getting started

Before using the Translation plugin you need to add/update a couple of files. The steps here are required if you have installed @pitcher/i18n package manually.

TIP

If you have installed @pitcher/i18n package through pitcherify cli, you can go to step 5 directly.

# 1. Add gettext.config.js

Create a file gettext.config.js in the root directory of your project and define languages and translations. This file is used by the package to extract, compile and translate the keys in your project. You can also configure various options with the help of this file.

// gettext.config.js

module.exports = {
  languages: {
    ar: 'Arabic',
    az: 'Azerbaijani',
    be: 'Belarusian',
    bg: 'Bulgarian',
    cs: 'Czech',
    da: 'Danish',
    de: 'German',
    el: 'Greek',
    en: 'English',
    es: 'Spanish',
    et: 'Estonian',
    fi: 'Finnish',
    fr: 'French',
    hi: 'Hindi',
    hr: 'Croatian',
    hu: 'Hungarian',
    id: 'Indonesian',
    it: 'Italian',
    ja: 'Japanese',
    ka: 'Georgian',
    kk: 'Kazakh',
    ko: 'Korean',
    ky: 'Kyrgyz',
    lt: 'Lithuanian',
    lv: 'Latvian',
    mk: 'FYRO Macedonian',
    ms: 'Malay',
    nl: 'Dutch',
    no: 'Norwegian',
    pl: 'Polish',
    pt: 'Portuguese',
    ro: 'Romanian',
    ru: 'Russian',
    sk: 'Slovak',
    sl: 'Slovenian',
    sq: 'Albanian',
    sr: 'Serbian',
    sw: 'Swahili',
    th: 'Thai',
    tr: 'Turkish',
    uk: 'Ukrainian',
    uz: 'Uzbek',
    vi: 'Vietnamese',
    'zh-CN': 'Chinese (Simplified)',
    'zh-TW': 'Chinese (Traditional)'
  },
  translations: [
    { category: 'app', type: 'source' },
    { category: 'app', type: 'package', package: '@pitcher/i18n' }
  ]
}

# Available Props

Property Default Description
languages undefined Languages you want to translate your project to
translations undefined Array of translations
output.po (optional) locale Output directory for .po files
output.json (optional) public/translations Output directory for .json files

# Required props for translations

Property Type Description
category String The category is used as filename {category}.pot and {category}.json
type source | package Parse messages from your source code or add messages provided by a package

# Optional props for type: 'source'

Property Type Default Description
patterns array ['src/**/*.js', 'src/**/*.vue', 'src/**/*.html'] Glob (opens new window) patterns to match files

# Optional props for type: 'package'

Property Type Default Description
packageCategory String undefined Define if the category named is different in your project and package

# 2. Update vue.config.js

Make sure you are importing available languages from gettext.config.json in your vue.config.js to add available languages as environment variables.

Example:

// vue.config.js

const languages = require('./gettext.config').languages

module.exports = {
  publicPath: '/',
  ...
  ...
}

process.env.VUE_APP_LANGUAGES = JSON.stringify(languages)

# 3. Add scripts to package.json

Add the scripts below to your package.json inside scripts: {} to be able to extract, compile and translate keys easily.

// package.json
scripts: {
  "gettext:extract": "npx config-gettext-extract",
  "gettext:compile": "npx config-gettext-compile",
  "gettext:generate": "npx config-gettext-generate",
  "gettext:translate": "export GOOGLE_APPLICATION_CREDENTIALS=google.json;npx config-gettext-translate"
}

# 4. Initialize plugin in main.js

After you have created your gettext.config.js and updated your vue.config.js, you need to initialize the plugin in your Vue application. To do this simply import TranslationPlugin from @pitcher/i18n and configure it.

Example:

// main.js

import { TranslationPlugin } from '@pitcher/i18n'

Vue.use(TranslationPlugin, {
  availableLanguages: JSON.parse(process.env.VUE_APP_LANGUAGES)
})

NOTE

Make sure it is imported AFTER @vue/composition-api and not before.

# 5. Setting language in App.vue

You could do this anywhere in your application, but as long as it is usual to set application language from the start it is recommended to set i18nStore language in App.vue just before the application is mounted. There are also multiple options to set the language. for example setting browser language as default or setting the user language inside params.

Setting browser language:



 







 
 
 
 




// app.vue

import { useI18nStore, useBrowserLanguage } from '@pitcher/i18n'

export default {
  setup() {
    // i18 store
    const i18n = useI18nStore()

    onMounted(async () => {
      // usage with browser language
      const { getAvailableBrowserLanguage } = useBrowserLanguage()
      const lang = getAvailableBrowserLanguage(Object.keys(i18n.state.availableLanguages))
      await i18n.setLanguage(lang)
    })
  }
}

Setting language from params:



 
 







 
 
 
 
 
 




// app.vue

import { useParamsStore } from '@pitcher/core'
import { useI18nStore } from '@pitcher/i18n'

export default {
  setup() {
    // i18 store
    const i18n = useI18nStore()

    onMounted(async () => {
      // usage with params
      const params = useParamsStore()

      // load: false does not load any translation files but supports dates and number formatting
      // default options are: { app = 'app', dir = 'translations', load = true }
      await i18n.setLanguage(params.locale.value, { load: false })
    })
  }
}

# Next steps

After you have completed the steps above, you are now ready to use translation plugin. See translations, scripts, API sections to find out how to translate your application.

← Translations →