quasalang

v1.1.1

Published

2 years ago

Generate Quasar i18n language files from a CSV file

Downloads

0High
0Medium
0Low

dannyconnell

quasar quasar framework i18n csv

Quasalang CLI

Generate all the i18n language files your Quasar Framework app needs - from a CSV file

Quasalang is a global CLI tool (for Quasar Framework projects) that allows you to generate all your i18n language files (including the main index.js file) instantly from a single, easy to update CSV file.

It will also generate a sample CSV file for you, so you can easily get started.

You can also:

Organise your phrases with empty lines & comments
Generate your language switcher array code
Search & list i18n locale codes easily

Quasalang CLI

Getting Started

Step 1: Install globally

$ npm install -g quasalang

Once installed, get yourself to the root of a Quasar project

$ cd my-quasar-project

Step 2: Generate a Sample CSV file

$ quasalang create-csv

This will generate a CSV file at /translations.csv that looks like this:

| Key | English, en-US | French, fr | German, de | |---------|----------------|------------|-----------------| | hello | Hello | Bonjour | Hallo | | goodbye | Goodbye | Au revoir | Auf Wiedersehen | | thanks | Thanks | Merci | Danke |

Key,"English, en-US","French, fr","German, de"
hello,"Hello","Bonjour","Hallo"
goodbye,"Goodbye","Au revoir","Auf Wiedersehen"
thanks,"Thanks","Merci","Danke"

Step 3: Add your own languages and translations

Use a CSV editor (such as the VSCode Extension "Edit csv") to add your own languages & phrases.

Be sure to use the format Language, code in the header row e.g. Russian, ru:

| Key | English, en-US | French, fr | German, de | Russian, ru | |----------|----------------|---------------------|-----------------|-----------------| | hello | Hello | Bonjour | Hallo | Привет | | goodbye | Goodbye | Au revoir | Auf Wiedersehen | До свидания | | thanks | Thanks | Merci | Danke | Спасибо | | buttHair | Butt hair | Cheveux bout à bout | Hintern Haare | стыковые волосы |

Key,"English, en-US","French, fr","German, de","Russian, ru"
hello,"Hello","Bonjour","Hallo",Привет
goodbye,"Goodbye","Au revoir","Auf Wiedersehen",До свидания
thanks,"Thanks","Merci","Danke",Спасибо
buttHair,"Butt hair","Cheveux bout à bout","Hintern Haare",стыковые волосы

Step 4: Generate your language files

Generate all the language files you need based on your CSV:

$ quasalang generate

By default, this will generate (or overwrite) your /src/i18n folder, generating all the files and folders you need:

src/
├─ i18n/
│  ├─ de/
│  │  ├─ index.js
│  ├─ en-US/
│  │  ├─ index.js
│  ├─ fr/
│  │  ├─ index.js
│  ├─ ru/
│  │  ├─ index.js
│  ├─ index.js

Your main index file /src/i18n/index.js will look like this:

// This file was auto-generated by Quasalang

import enUS from './en-US'
import fr from './fr'
import de from './de'
import ru from './ru'

export default { 
  'en-US': enUS, // English
  'fr': fr, // French
  'de': de, // German
  'ru': ru, // Russian
}

And your language files, e.g. /src/i18n/ru/index.js will look like this:

// Russian, ru
// This file was auto-generated by Quasalang

export default {
  hello: `Привет`,
  goodbye: `До свидания`,
  thanks: `Спасибо`,
  buttHair: `стыковые волосы`,
}

Options

Input Path

The default input path is /translations.csv but you can change it if you like:

$ quasalang generate --input /files/my-translations.csv

# or the shorthand...

$ quasalang g -i /files/my-translations.csv

Output Path

The default output path is /src/i18n but you can change it if you like:

$ quasalang generate --output /src/my-translations

# or the shorthand...

$ quasalang g -o /src/my-translations

Force Write

By default, if the output folder exists, you'll be prompted to overwrite it:

? Folder src/i18n exists. Overwrite it? (Y/n)

You can skip this prompt if you like:

$ quasalang generate --force

# or the shorthand...

$ quasalang g -f

No Watermark

By default, Quasalang will add a watermark to your files:

// This file was auto-generated by Quasalang

You can disable this if you like:

$ quasalang generate --nowatermark

# or the shorthand...

$ quasalang g -nw

Language Switcher Array Code

You also generate the array code for your language switcher:

$ quasalang generate --lang-switcher

# or the shorthand...

$ quasalang g -ls

See Generate language switcher array code for more info.

Watch for changes

You can watch for changes to your translation file and auto-regenerate your language files. You can then just leave it running in the background and forget about it:

$ quasalang generate --watch

# or the shorthand...

$ quasalang g -w

Advanced Features

Use Empty Rows to Split Up Your Phrases

You can leave empty rows in your CSV file, like this:

| Key | English, en-US | French, fr | German, de | Russian, ru | |----------|----------------|---------------------|-----------------|-----------------| | | | | | | | hello | Hello | Bonjour | Hallo | Привет | | goodbye | Goodbye | Au revoir | Auf Wiedersehen | До свидания | | thanks | Thanks | Merci | Danke | Спасибо | | | | | | | | buttHair | Butt hair | Cheveux bout à bout | Hintern Haare | стыковые волосы | | | | | | |

Key,"English, en-US","French, fr","German, de","Russian, ru"
,,,,
hello,"Hello","Bonjour","Hallo",Привет
goodbye,"Goodbye","Au revoir","Auf Wiedersehen",До свидания
thanks,"Thanks","Merci","Danke",Спасибо
,,,,
buttHair,"Butt hair","Cheveux bout à bout","Hintern Haare",стыковые волосы
,,,,

And this will generate equivalent empty lines in your generated language files:

// Russian, ru
// This file was auto-generated by Quasalang

export default {

  hello: `Привет`,
  goodbye: `До свидания`,
  thanks: `Спасибо`,
  
  buttHair: `стыковые волосы`,

}

Use Comments to Organise your Phrases

You can add comments to your CSV file to create sections like this:

| Key | English, en-US | French, fr | German, de | Russian, ru | |----------------|----------------|---------------------|-----------------|-----------------| | | | | | | | # Greetings | | | | | | hello | Hello | Bonjour | Hallo | Привет | | goodbye | Goodbye | Au revoir | Auf Wiedersehen | До свидания | | thanks | Thanks | Merci | Danke | Спасибо | | | | | | | | # Hair Related | | | | | | buttHair | Butt hair | Cheveux bout à bout | Hintern Haare | стыковые волосы | | | | | | |

Key,"English, en-US","French, fr","German, de","Russian, ru"
,,,,
# Greetings
hello,"Hello","Bonjour","Hallo",Привет
goodbye,"Goodbye","Au revoir","Auf Wiedersehen",До свидания
thanks,"Thanks","Merci","Danke",Спасибо
,,,,
# Hair Related
buttHair,"Butt hair","Cheveux bout à bout","Hintern Haare",стыковые волосы
,,,,

And this will add equivalent comments to your generated files:

// Russian, ru
// This file was auto-generated by Quasalang

export default {

  // Greetings
  hello: `Привет`,
  goodbye: `До свидания`,
  thanks: `Спасибо`,
  
  // Hair Related
  buttHair: `стыковые волосы`,

}

Use Strings as Your Keys

If you want to use strings as your keys, just surround your keys in double quotes:

| Key | English, en-US | French, fr | German, de | |---------------|----------------|------------|-----------------| | "Hello" | Hello | Bonjour | Hallo | | "Goodbye" | Goodbye | Au revoir | Auf Wiedersehen | | "Thanks" | Thanks | Merci | Danke |

Key,"English, en-US","French, fr","German, de"
"""Hello""","Hello","Bonjour","Hallo"
"""Goodbye""","Goodbye","Au revoir","Auf Wiedersehen"
"""Thanks""","Thanks","Merci","Danke"

This will generate language files like this:

// French, fr
// This file was auto-generated by Quasalang

export default {
  "Hello": `Bonjour`,
  "Goodbye": `Au revoir`,
  "Thanks": `Merci`,
}

Add Multi-Line Phrases

You can add multi-line phrases, like in the last row here:

| Key | English, en-US | French, fr | German, de | |---------|--------------------------------------------------------|----------------------------------------------------------------|----------------------------------------------------------| | hello | Hello | Bonjour | Hallo | | goodbye | Goodbye | Au revoir | Auf Wiedersehen | | thanks | Thanks | Merci | Danke | | welcome | Hey there...Welcome to the app!...Hope you like it! | Salut...Bienvenue dans l'appli! ...J'espère que vous aimez! | Sie da...Willkommen in der App! ...Hoffe du magst es! |

Key,"English, en-US","French, fr","German, de"
hello,"Hello","Bonjour","Hallo"
goodbye,"Goodbye","Au revoir","Auf Wiedersehen"
thanks,"Thanks","Merci","Danke"
welcome,"Hey there...
Welcome to the app!...

Hope you like it!","Salut...
Bienvenue dans l'appli! ...

J'espère que vous aimez!","Sie da...
Willkommen in der App! ...

Hoffe du magst es!"

This will generate language files like this:

// English, en-US
// This file was auto-generated by Quasalang

export default {
  hello: `Hello`,
  goodbye: `Goodbye`,
  thanks: `Thanks`,
  welcome: `Hey there...
Welcome to the app!...

Hope you like it!`,
}

Extra Tools

Generate language switcher array code

You can generate the code for your language switcher array (based on your CSV):

$ quasalang lang-switcher

# or the shorthand...

$ quasalang ls

This will output something like this to the console:

Your language switcher options array:

[
  { label: 'English', value: 'en-US' },
  { label: 'French', value: 'fr' },
  { label: 'German', value: 'de' }
]

You can also run this command automatically when you use the generate command to generate your language files:

$ quasalang generate --lang-switcher

# or the shorthand...

$ quasalang g -ls

The output will be something like this

Wrote 4 files:
┌─────────┬───────────────────┬─────────┬───────────────────────────┐
│ (index) │       File        │  Code   │           Path            │
├─────────┼───────────────────┼─────────┼───────────────────────────┤
│    0    │ 'Main index file' │   ''    │    'src/i18n/index.js'    │
│    1    │     'English'     │ 'en-US' │ 'src/i18n/en-US/index.js' │
│    2    │     'French'      │  'fr'   │  'src/i18n/fr/index.js'   │
│    3    │     'German'      │  'de'   │  'src/i18n/de/index.js'   │
└─────────┴───────────────────┴─────────┴───────────────────────────┘

Your language switcher options array:

[
  { label: 'English', value: 'en-US' },
  { label: 'French', value: 'fr' },
  { label: 'German', value: 'de' }
]

Search and List i18n Locale Codes

Don't know the locale code for a language? Just search for it:

$ quasalang list-codes

? Enter a search query (e.g. "russian") or hit Enter to list all codes: italian


  _____ 
 |_   _|
   | |  
   | |  
  _| |_ 
 |_____|
        
        
Italian, it
Italian (Italy), it_IT
Italian (Switzerland), it_CH

Or just hit enter to list them all:

           
     /\    
    /  \   
   / /\ \  
  / ____ \ 
 /_/    \_\
           
           
Afrikaans, af
Afrikaans (Namibia), af_NA
Afrikaans (South Africa), af_ZA
Akan, ak
Akan (Ghana), ak_GH
Albanian, sq
Albanian (Albania), sq_AL
Amharic, am
Amharic (Ethiopia), am_ET
Arabic, ar
Arabic (Algeria), ar_DZ
Arabic (Bahrain), ar_BH
Arabic (Egypt), ar_EG
Arabic (Iraq), ar_IQ
Arabic (Jordan), ar_JO
Arabic (Kuwait), ar_KW
Arabic (Lebanon), ar_LB
Arabic (Libya), ar_LY
Arabic (Morocco), ar_MA
Arabic (Oman), ar_OM
Arabic (Qatar), ar_QA
Arabic (Saudi Arabia), ar_SA
Arabic (Sudan), ar_SD
Arabic (Syria), ar_SY
Arabic (Tunisia), ar_TN
Arabic (United Arab Emirates), ar_AE
Arabic (Yemen), ar_YE
Armenian, hy
Armenian (Armenia), hy_AM
Assamese (India), as_IN
Assamese, as
Asu, asa
Asu (Tanzania), asa_TZ
Azerbaijani, az
Azerbaijani (Cyrillic), az_Cyrl
Azerbaijani (Cyrillic, Azerbaijan), az_Cyrl_AZ
Azerbaijani (Latin), az_Latn
Azerbaijani (Latin, Azerbaijan), az_Latn_AZ


  ____  
 |  _ \ 
 | |_) |
 |  _ < 
 | |_) |
 |____/ 
        
        
Bambara, bm
Bambara (Mali), bm_ML
Basque, eu
Basque (Spain), eu_ES

... etc ...

You can then copy and paste your language name and code straight into your CSV column header.

Commands

`generate`

Usage: quasalang generate|g [options]

Generate your i18n folder & all language files based on a CSV file

Options:
  -i, --input <mode>    Path to input CSV (default: "translations.csv")
  -o, --output <mode>   Path to i18n output folder (default: "src/i18n")
  -f, --force           Force write files (without prompt) (default: false)
  -nw, --nowatermark    Disable the watermark ("This file was auto-generated..")  (default:
                        false)
  -ls, --lang-switcher  Generate language switcher options array & output to console i.e. [{
                        label: 'English', value: 'en-US'}, ..] (default: false)
  -w, --watch           Watch CSV file for changes & regenerate files (default: false)
  -h, --help            display help for command

`create-csv`

Usage: quasalang create-csv|c [options]

Create a sample CSV file (/translations.csv)

Options:
  -f, --force  Force overwrite translations file (without prompt) (default: false)
  -h, --help   display help for command

`lang-switcher`

Usage: quasalang lang-switcher|ls [options]

Generate language switcher options array & output to console i.e. [{ label: 'English', value: 'en-US'}, ..]

Options:
  -i, --input <mode>  Path to input CSV (default: "translations.csv")
  -h, --help          display help for command

`list-codes`

Usage: quasalang list-codes|lc [options]

Search & list i18n locale codes

Options:
  -h, --help  display help for command