vue-gettext-cli

Localization workflow command-line interface for Vue.JS web application.

This utility is based on the proposed workflow for the vue-gettext plugin package.

This command-line interface uses the easygettext tools to extract the annotated strings to portable object (.po) files and convert them back to JavaScript Object Notation (.json).

Dependencies

This package relies on the GNU gettext toolset (tested with version 0.19.8.1). Precompiled binaries for Windows can be found here.

Important: Make sure to add the path to the gettext binaries (msginit, msgmerge and msgattrib) to your PATH environment variable.

Install

This package can be installed as a development dependency using NPM or Yarn.

NPM

npm install vue-gettext-cli --save-dev

Yarn

yarn add vue-gettext-cli --dev

Usage

vue-gettext-cli <command> [options]

To display the options for each available commands:

vue-gettext-cli extract --help 
vue-gettext-cli compile --help

Commands

Extract

vue-gettext-cli extract [options]

Extract annotated string to translate from template / javascript files.

Options:

--version             Display version number                [boolean]
--help, -h            Display command help                  [boolean]
--verbose, -v         Display more info during process      [boolean] [default: false]
--source, -s          Path to source folder                 [string]  [default: "./src"]
--destination, -d     Path to translations output folder    [string]  [default: "./translations"]
--locales, -l         Locales prefixes list                 [array]   [default: ["en"]]
--extensions, -e      Supported file extensions list        [array]   [default: ["jade", "html", "htm", "js", "pug", "vue", "ts"]]
--startDelimiter, -sd Custom start delimiter                [string]  [default: "{{"] 
--endDelimiter, -ed   Custom end delimiter                  [string]  [default: "}}"]  
--template, -p        Name of the generated portable object [string]  [default: "template.pot"]
                      template (.pot) file

Compile

vue-gettext-cli compile [options]

Compile portable object (.po) translation files to JavaScript Object Notation (.json) file(s).

Options:

--version          Display version number                     [boolean]
--help, -h         Display command help                       [boolean]
--verbose, -v      Display more info during process           [boolean] [default: false]
--source, -s       Path to portable object (.po) files folder [string]  [default: "./translations/locales"]
--destination, -d  Path to translations folder                [string]  [default: "./src/translations"]
--locales, -l      Locales prefixes list                      [array]   [default: ["en"]]
--combined, -c     Compile translations to a single file      [boolean] [default: false]

Workflow

1. Annotate

Edit the Vue.JS templates files (.html, .vue, .jade, .js) and annotate each translatable string as required for your application localization using the tokens supported by the easygettext's extract tools.

2. Extract

Locate and parse each source files matching the list of extensions specified to generate the portable object template (.pot). Then create or update the portable object (.po) for each locales specified using the previously generated .pot file.

The vue-gettext-cli extract command can be use to streamline the process of creating the po locales. For example, using the default values:

vue-gettext-cli extract

This command will look for *.jade, *.html, *.js and *.vue extensions file within the relative ./src source folder. It will then extract annotated tokens to generate a template.pot file in the ./translations folder and finally create or update the en (english) locale ./translations/locales/en.po file.

3. Translate

Having generated the translation file(s) in the previous step, you can now use an application like Poedit to edit and update the gettext translations (.po) files for each supported language of your application.

4. Convert

Locate and parse the updated gettext translations (.po) files and compile each of the locales to JavaScript Notation Object (.json) format. The compile operation can generate a single .json file containing all locales (by specifying the --combined option) or split each locale to its own .json file.

The vue-gettext-cli compile command can be used to convert from the .po locales to .json file format. For example, using the default values:

vue-gettext-cli compile

This command will look for *.po extension file(s) within the relative ./translations/locales folder that matches the en(english) locale. It will then generate an en.json file in the ./src/translations folder. The JSON format translations file can then be used with the vue-gettext plugin to localize your Vue.JS web application.

For additional locales, the --locales option can be used to specify a list of space separated locales ids. For example to process locales for english (en), french (fr_FR) and spanish (es), you would call the compile command as follow:

vue-gettext-cli compile --locales en fr_FR es

Remark: this command will only process locales for which a .po file exists.

Exemple

The following presents a step-by-step workflow configuration using a generic Vue.JS project with vue-gettext for localization support.

1. Create a new Vue.JS project using Vue CLI 3.

vue create my-project

Remark: a default project configuration is used for this example.

Then change to the newly created project directory.

cd my-project 

2. Install the vue-gettext plugin as a dependency.

npm install vue-gettext --save

3. Install the vue-gettext-cli tool as a development dependency.

npm install vue-gettext-cli --save-dev

Note: remember to install GNU gettext toolset and include the binaries to your PATH environment variable.

4. Edit the HelloWorld component as follow:

./src/components/HelloWorld.vue

<template>
  <div class="hello">
    <select name="language" :value="$language.current" @change="onChange">
      <option v-for="(value, key) in $language.available" :value="key" :key="key">{{ value }}</option>
    </select>
    <h3>    
      <translate>#WELCOME#</translate>
    </h3>
  </div>
</template>

<script>
import Vue from 'vue'

export default {
  name: 'HelloWorld',
  methods:{
      onChange(event){
          const value = event.target.value;

          // Only load locale translation if not previously loaded
          if (!Vue.$translations.hasOwnProperty(value)) {

            import('@/translations/' + value + '.json').then( (locale) => {        
              this.$language.merge(locale);
              this.$language.current = value;
            })       

          } else {          
            this.$language.current = value;
          }
      }
    }
}
</script>	

<!-- Add "scoped" attribute to limit CSS to this component only -->
<style scoped>
h3 {
  margin: 40px 0 0;
}
ul {
  list-style-type: none;
  padding: 0;
}
li {
  display: inline-block;
  margin: 0 10px;
}
a {
  color: #42b983;
}
</style>

5. Edit the package.json to add tasks to run extract and compile translations to the scripts section for english, french and spanish locales.

package.json

{ 
  ... 
  "scripts": {
	...		
	"localize-extract": "vue-gettext-cli extract --locales en fr es",
	"localize-compile": "vue-gettext-cli compile --locales en fr es"		
  },
  ...
}

6. Extract the annnotated strings from the HelloWorld component.

npm run localize-extract

Extracting annotated strings...
[easygettext] extracting: './src/App.vue
[easygettext] extracting: './src/components/HelloWorld.vue
[easygettext] extracting: './src/main.js
./translations/locales/en.po created.
./translations/locales/fr.po created.
./translations/locales/es.po created.

Now you can edit each .po file using Poedit and set the #WELCOME# value for each locales.

7. Convert the edited .po translations to .json files for each locales.

npm run localize-compile

Compiling locales to separate json files...
[gettext] processing PO file: ./translations/locales/en.po
[gettext] processing PO file: ./translations/locales/fr.po
[gettext] processing PO file: ./translations/locales/es.po

8. Update the project's main.js file to use the translations with the vue-gettext plugin.

main.js

import Vue from 'vue'		
import App from './App.vue'
import GetTextPlugin from 'vue-gettext'	

// Default translations to english language
import translations from '@/translations/en.json'

Vue.config.productionTip = false

Vue.use(GetTextPlugin,{
  availableLanguages: {
    en: 'English',
    es: 'Spanish',
    fr: 'Français'
  },
  defaultLanguage: 'en',
  languageVmMixin: {
    methods: {
      merge (locale) {
        Object.assign(translations, locale);        
      },
    }
  },
  translations: translations,
  silent: true,
})

new Vue({

  created () {
    const ll_CC = navigator.language || navigator.userLanguage;     
    const language = ll_CC.split("-", 1);

    if (!Vue.$translations.hasOwnProperty(language)){

      import('@/translations/' + language + '.json').then( (locale) => {        
        this.$language.merge(locale);
        this.$language.current = language;      
      })       
    } 
  },

  render: h => h(App),
}).$mount('#app')

9. Run the local server.

npm run serve

Now you can access the web application on the local server url (usually http://localhost:8080).

10. Test localization

By default, the web application will initially import and select english language locale. If your current browser language is one of the declared locales, it should automatically be loaded and selected.

The selection of another (not previously selected) language will trigger an import call to load the corresponding locale.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---