toloko

Toloko is Sesotho for interpreter.

Introduction

Toloko is a text translation tool for the command line that supports dozens of source and target languages. It requires a terminal emulator that supports UTF-8 encoding; I prefer Terminator. For more info, see the wiki.

Installation

To initialize the config file and load themes, your NODE_PATH environment variable must point to the lib/node_modules directory of the Node.js installation. You can set this path automatically like this:

export NP=$(which node)
export BP=${NP%bin/node} #this replaces the string '/bin/node'
export LP="${BP}lib/node_modules"
export NODE_PATH="$LP"

Provided these lines are towards the end of the shell initialization file (at least after any NVM stuff) this should work for a system installation of Node.js and nvm.

Add all of this to .bashrc, .zshrc, Windows env, etc. then:

npm install -g toloko
toloko config init

Usage

toloko has a built-in help system for CLI parameters and options. Access it with toloko -h|--help [command] [subcommand]. There is also the wiki.

Here are some examples:

// Get a translated sentence with the word 'tree' in German from Glosbe
toloko gl ex --source eng --target deu tree

// Translate 'despues' from Spanish to English using Hablaa
toloko ha tr -s spa -t eng despues

// List Hablaa's supported languages
toloko ha ls

// Translate 'hello' from English to Russian using Yandex
toloko yx tr --dir en-ru hello

// Detect language using Yandex
toloko yx dt привет

// List Yandex's supported languages
toloko yx ls

See the tests for more.

Trinity

Toloko is one of three command line utilities along with Leximaven and iloa that puts enormous power at your fingertips. Try them alone or together!

Resources

These following links can help you use Toloko or perform related tasks.

  • A list of ISO 639-1 and 639-2 language codes can be helpful in setting the source and target languages.
  • Google Translate is not perfect, but it does perform translation & transliteration in realtime (as you type). It even provides sound clips (some pre-recorded, some synthesized).
  • Yandex Translate is similar to Google Translate
  • Omniglot is an amazing resource for learning about languages, writing systems, and related topics.
  • translit.cc Translation & transliteration services w/ virtual keyboards for Armenian, Belarusian, Bulgarian, Georgian, Greek, Russian, and Ukranian, plus other useful tools like spell-checking.
  • romaji.me Transliterate between Japanese text (Kanji, Hiragana, Katakana) and English.

Gratitude

Many thanks to all contributors to the gems used in this project! And thanks to the creators and maintainers of the APIs that this tool consumes. Glosbe, Hablaa and Yandex are awesome!

Powered by Hablaa

Powered by Yandex.Translate

Table of Contents

Completion

iloa command: completion, comp

Bash instructions

Run toloko comp >> ~/.bashrc, then source ~/.bashrc to enable shell completion for toloko commands and options.

Zsh instructions

To Zsh read your bash script, add to ~/.zshrc:
autoload bashcompinit
bashcompinit

Now run toloko comp >> ~/.zshrc and source ~/.zshrc.

Configuration

Toloko can get and set values in the configuration file once it’s been initialized. Toloko uses the dotty library to allow dot notation for nested values. See the FAQ for why I chose noon for the configuration file format.

Toloko command: config

Toloko subcommands:

  • init, i - Creates configuration file in home directory (~/.iloa.noon)
  • get, g - Gets a value for a given key. Accepts dot notation for nested values.
  • set, s - Sets a given key to a given value. Accepts dot notation for nested values.

Examples

For globals like verbose you can just do toloko config set verbose true. For nested properties, use dot notation like so:

1
2
3
4
5
$ toloko config get glosbe.translate.author
Option glosbe.translate.author is true.
$ toloko config set glosbe.translate.author true
Set option glosbe.translate.author to true.

Saving flags

By default, the merge option is set to true, so CLI flags will be merged with the configuration from file. If you pass -s|–save with this, the config file will be overwritten with the current flags. If merge is set to false, the config file will always be used and –save won’t work. To restore all defaults run toloko config init --force.

Editing

Refer to the noon syntax guide. When editing the configuration file manually, please remember that empty strings are denoted by two pipes: || and 2 or more spaces separate keys from values.

Engine

  • chalk, ora, and yargonaut are used to style the terminal output.
  • moment manipulates timestamps for rate limiting.
  • good-guy-http gets and caches HTTP requests.
  • yargs is used for creating the CLI.
  • xml2js is used for XML format, and noon is used for all other formats.

Frequently (or Never) Asked Questions

What is noon?

noon, or ‘nother ordinary object notation, is a human-readable data format created by monsterkodi. Despite noon being very new, I decided to use it for Leximaven’s configuration file because it is incredibly terse, even more so than hjson and cson. This is me supporting a young project that I would like to see get wider recognition. It also makes it dead simple to load and save cson, json, plist, and yaml.

Features

  • Extensible
  • Configuration file in your home directory called .toloko.noon
  • Access configuration settings by passing commands, setting flags, or just editing the configuration file manually
  • Sensible command line defaults and aliases
  • XML parsing and building with xml2js
  • good-guy-http client with in-memory caching and other neat features. Under the hood is request.
  • Save data to CSON, JSON, noon, Plist, XML, and YAML
  • Translations and examples from Glosbe
  • Translations from Hablaa
  • Translations and language detection from Yandex

Formats

Toloko supports the following file formats:

  • noon - Whitespace-sensitive terse data format created by @monsterkodi, here used for the configuration and theme systems. See FAQ.
  • Plain JSON
  • Plain XML
  • CSON - JSON for Coffeescript objects
  • Plist - OSX/iOS data format
  • YAML - Human Readable data format

Glosbe

From glosbe.com:

Glosbe provides free dictionaries for almost every existing language and translation memory with over a billion sentences included.

Toloko command: glosbe, gl

Glosbe subcommands:

  • example, ex - Provides translation examples containing a word
  • translate, trans, tr - Translates a word

Hablaa

From hablaa.com:

Hablaa provides free translations from and into more than 160 languages.

Toloko command: hablaa, ha

Hablaa subcommands:

  • list, langs, ls - Lists supported languages
  • translate, trans, tr - Translates a word

New APIs

Adding new APIs to iloa is pretty straightforward. Look at the docs for yargs to understand the module format. As an example, here’s Hablaa’s translate module.

Each module registers a command with yargs. The command string defines the command and arguments. The builder object defines our options. The handler function contains our command logic.

After configuration checks and theme loading, we assemble the URL from the parsed arguments, argv. good-guy-http fetches the JSON response. For each piece of data that is printed in the console, the same data is added to the tofile object. If --out is specified, this object is passed to tools.outFile which is then encoded and saved. Finally, if --save is specified, options are saved to configuration.

Yandex

The Yandex.Translate API is a universal text translation tool that uses machine translation technology developed at Yandex. It allows developers to integrate machine translation into their applications, services, and sites. Translation is currently available for more than 80 languages.

Developers of small translation projects, which do not exceed 10,000,000 characters a month (and no more than 1,000,000 in 24 hours), can use the Yandex.Translate API for free.

Toloko command: yandex, yx

Yandex subcommands:

  • detect, dt - Detects the language being used
  • list, langs, ls - Lists the supported languages
  • translate, tr - Translates a word