1# Translate Shell 2 3[![Icon](https://raw.githubusercontent.com/soimort/translate-shell/gh-pages/images/icon.png)](https://www.soimort.org/translate-shell) 4[![CircleCI](https://circleci.com/gh/soimort/translate-shell.svg?style=svg)](https://circleci.com/gh/soimort/translate-shell) 5[![Actions](https://github.com/soimort/translate-shell/workflows/CI/badge.svg)](https://github.com/soimort/translate-shell/actions) 6[![Version](https://raw.githubusercontent.com/soimort/translate-shell/gh-pages/images/badge-release.png)](https://github.com/soimort/translate-shell/releases) 7[![Download](https://raw.githubusercontent.com/soimort/translate-shell/gh-pages/images/badge-download.png)](https://www.soimort.org/translate-shell/trans) 8[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/soimort/translate-shell?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 9 10**[Translate Shell](https://www.soimort.org/translate-shell)** (formerly _Google Translate CLI_) is a command-line translator powered by **[Google Translate](https://translate.google.com/)** (default), **[Bing Translator](https://www.bing.com/translator)**, **[Yandex.Translate](https://translate.yandex.com/)**, and **[Apertium](https://www.apertium.org/)**. It gives you easy access to one of these translation engines in your terminal: 11 12``` 13$ trans 'Saluton, Mondo!' 14Saluton, Mondo! 15 16Hello, World! 17 18Translations of Saluton, Mondo! 19[ Esperanto -> English ] 20Saluton , 21 Hello, 22Mondo ! 23 World! 24``` 25 26By default, translations with detailed explanations are shown. You can also translate the text briefly: (only the most relevant translation will be shown) 27 28``` 29$ trans -brief 'Saluton, Mondo!' 30Hello, World! 31``` 32 33**Translate Shell** can also be used like an interactive shell; input the text to be translated line by line: 34 35``` 36$ trans -shell -brief 37> Rien ne réussit comme le succès. 38Nothing succeeds like success. 39> Was mich nicht umbringt, macht mich stärker. 40What does not kill me makes me stronger. 41> Юмор есть остроумие глубокого чувства. 42Humor has a deep sense of wit. 43> 學而不思則罔,思而不學則殆。 44Learning without thought is labor lost, thought without learning is perilous. 45> 幸福になるためには、人から愛されるのが一番の近道。 46In order to be happy, the best way is to be loved by people. 47``` 48 49## Prerequisites 50 51### System Requirements 52 53**Translate Shell** is known to work on many POSIX-compliant systems, including but not limited to: 54 55* GNU/Linux 56* macOS 57* *BSD 58* Android (through Termux) 59* Windows (through WSL, Cygwin, or MSYS2) 60 61### Dependencies 62 63* **[GNU Awk](https://www.gnu.org/software/gawk/)** (**gawk**) **4.0 or later** 64 * This program relies heavily on GNU extensions of the [AWK language](http://en.wikipedia.org/wiki/AWK), which are non-portable for other AWK implementations (e.g. nawk). 65 * How to get gawk: 66 * gawk comes with all GNU/Linux distributions. 67 * On FreeBSD, gawk is available in the ports. 68 * On macOS, gawk is available in MacPorts and Homebrew. 69* **[GNU Bash](http://www.gnu.org/software/bash/)** or **[Zsh](http://www.zsh.org/)** 70 * You may use Translate Shell from any Unix shell of your choice (bash, zsh, ksh, tcsh, fish, etc.); however, the wrapper script requires either **bash** or **zsh** installed. 71 72### Recommended Dependencies 73 74These dependencies are optional, but strongly recommended for full functionality: 75 76* **[curl](http://curl.haxx.se/)** with **OpenSSL** support 77* **[GNU FriBidi](http://fribidi.org/)**: _an implementation of the Unicode Bidirectional Algorithm (bidi)_ 78 * required for displaying text in Right-to-Left scripts (e.g. Arabic, Hebrew) 79* **[mplayer](http://www.mplayerhq.hu/)**, **[mpv](http://mpv.io/)**, **[mpg123](http://mpg123.org/)**, or **[eSpeak](http://espeak.sourceforge.net/)** 80 * required for the Text-to-Speech functionality 81* **[less](http://www.greenwoodsoftware.com/less/)**, **[more](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/more.html)** or **[most](http://www.jedsoft.org/most/)** 82 * required for terminal paging 83* **[rlwrap](http://utopia.knoware.nl/~hlub/uck/rlwrap/#rlwrap)**: *a GNU readline wrapper* 84 * required for readline-style editing and history in the interactive shell 85* **[aspell](http://aspell.net/)** or **[hunspell](http://hunspell.github.io/)** 86 * required for spell checking 87 88### Environment and Fonts 89 90It is a must to have corresponding fonts for the language(s) / script(s) you wish to display in your terminal. See **[wiki: Writing Systems and Fonts](https://github.com/soimort/translate-shell/wiki/Writing-Systems-and-Fonts#unicode-fonts)** for more details on scripts and recommended Unicode fonts. 91 92## Try It Out! 93 94Start an interactive shell and translate anything you input into your native language: (in **bash** or **zsh**) 95 96 $ gawk -f <(curl -Ls git.io/translate) -- -shell 97 98(in **fish**) 99 100 $ gawk -f (curl -Ls git.io/translate | psub) -- -shell 101 102### Using Docker 103 104To try out via [Docker](https://www.docker.com/), run: 105 106 $ docker pull soimort/translate-shell 107 108Then you may start an interactive shell from the Docker image for translating: 109 110 $ docker run -it soimort/translate-shell -shell 111 112## Installation 113 114### Option #1. Direct Download 115 116Download [the self-contained executable](http://git.io/trans) and place it into your path. It's everything you need. 117 118 $ wget git.io/trans 119 $ chmod +x ./trans 120 121There is a [GPG signature](https://www.soimort.org/translate-shell/trans.sig). 122 123### Option #2. From A Package Manager 124 125#### Using your favorite package manager 126 127See **[wiki: Distros](https://github.com/soimort/translate-shell/wiki/Distros)** on how to install from a specific package manager on your distro. 128 129#### Using [Antigen](https://github.com/zsh-users/antigen) (for Zsh users) 130 131Add the following line to your `.zshrc`: 132 133 antigen bundle soimort/translate-shell 134 135### Option #3. From Git 136 137 $ git clone https://github.com/soimort/translate-shell 138 $ cd translate-shell/ 139 $ make 140 $ [sudo] make install 141 142In case you have only zsh but not bash in your system, build with: 143 144 $ make TARGET=zsh 145 146The default `PREFIX` of installation is `/usr/local`. To install the program to somewhere else (e.g. `/usr`, `~/.local`), use: 147 148 $ [sudo] make PREFIX=/usr install 149 150## Getting Started by Examples 151 152### Translate a Word 153 154#### From any language to your language 155 156Google Translate can identify the language of the source text automatically, and Translate Shell by default translates the source text into the language of your `locale`. 157 158 $ trans vorto 159 160#### From any language to one or more specific languages 161 162Translate a word into French: 163 164 $ trans :fr word 165 166Translate a word into Chinese and Japanese: (use a plus sign "`+`" as the delimiter) 167 168 $ trans :zh+ja word 169 170Alternatively, equals sign ("`=`") can be used in place of the colon ("`:`"). Note that in some shells (e.g. zsh), equals signs may be interpreted differently, therefore the argument specifying languages needs to be protected: 171 172 $ trans {=zh+ja} word 173 $ trans '=zh+ja' word 174 175You can also use the `-target` (`-t`) option to specify the target language(s): 176 177 $ trans -t zh+ja word 178 179With the `-t` option, the name of the language may also be used instead of the language code: 180 181 $ trans -t japanese word 182 $ trans -t 日本語 word 183 184#### From a specific language 185 186Google Translate may wrongly identify the source text as some other language than you expected: 187 188 $ trans 手紙 189 190In that case, you need to specify its language explicitly: 191 192 $ trans ja: 手紙 193 $ trans zh: 手紙 194 195You can also use the `-source` (`-s`) option to specify the source language: 196 197 $ trans -s ja 手紙 198 199### Translate Multiple Words or a Phrase 200 201Translate each word alone: 202 203 $ trans en:zh word processor 204 205Put words into one argument, and translate them as a whole: 206 207 $ trans en:zh "word processor" 208 209### Translate a Sentence 210 211Translating a sentence is much the same like translating a phrase; you can just quote the sentence into one argument: 212 213 $ trans :zh "To-morrow, and to-morrow, and to-morrow," 214 $ trans :zh 'To-morrow, and to-morrow, and to-morrow,' 215 216It is also possible to translate multi-line sentences: 217 218 $ trans :zh "Creeps in this petty pace from day to day, 219 > To the last syllable of recorded time; 220 > And all our yesterdays have lighted fools 221 > The way to dusty death." 222 223To avoid punctuation marks (e.g. "`!`") or other special characters being interpreted by the shell, use *single quotes*: 224 225 $ trans :zh 'Out, out, brief candle!' 226 227There are some cases though, you may still want to use *double quotes*: (e.g. the sentence contains a single quotation mark "`'`") 228 229 $ trans :zh "Life's but a walking shadow, a poor player" 230 231Alternatively, use the `-join-sentence` (`-j`) option to treat all arguments as one sentence so that quotes can be omitted: 232 233 $ trans -j :zh Life\'s but a walking shadow, a poor player 234 235### Brief Mode 236 237By default, Translate Shell displays translations in a verbose manner. If you prefer to see only the most relevant translation, there is a brief mode available using the `-brief` (`-b`) option: 238 239 $ trans -b :fr "Saluton, Mondo" 240 241In brief mode, phonetic notation (if any) is not shown by default. To enable this, put an at sign "`@`" in front of the language code: 242 243 $ trans -b :@ja "Saluton, Mondo" 244 245### Dictionary Mode 246 247Google Translate can be used as a dictionary. When translating a word and the target language is the same as the source language, the dictionary entry of the word is shown: 248 249 $ trans :en word 250 251To enable dictionary mode no matter whether the source language and the target language are identical, use the `-dictionary` (`-d`) option. 252 253 $ trans -d fr: mot 254 255**Note:** Not every language supported by Google Translate has provided dictionary data. See **[wiki: Languages](https://github.com/soimort/translate-shell/wiki/Languages)** to find out which language(s) has dictionary support. 256 257### Language Identification 258 259Use the `-identify` (`-id`) option to identify the language of the text: 260 261 $ trans -id 言葉 262 263### Text-to-Speech 264 265Use the `-play` (`-p`) option to listen to the translation: 266 267 $ trans -b -p :ja "Saluton, Mondo" 268 269Use the `-speak` (`-sp`) option to listen to the original text: 270 271 $ trans -sp "你好,世界" 272 273### Terminal Paging 274 275Sometimes the content of translation can be too much for display in one screen. Use the `-view` (`-v`) option to view the translation in a terminal pager such as `less` or `more`: 276 277 $ trans -d -v word 278 279### Right-to-Left (RTL) Languages 280 281[Right-to-Left (RTL) languages](http://en.wikipedia.org/wiki/Right-to-left) are well supported via [GNU FriBidi](http://fribidi.org/). 282 283The program will automatically adjust the screen width for padding when displaying right-to-left languages. Alternatively, you may use the `-width` (`-w`) option to specify the screen width: 284 285 $ trans -b -w 40 :he "Saluton, Mondo" 286 287See **[wiki: Languages](https://github.com/soimort/translate-shell/wiki/Languages)** to find out which language(s) uses a Right-to-Left writing system. 288 289### Pipeline, Input and Output 290 291If no source text is given in command-line arguments, the program will read from standard input, or from the file specified by the `-input` (`-i`) option: 292 293 $ echo "Saluton, Mondo" | trans -b :fr 294 $ trans -b -i input.txt :fr 295 296Translations are written to standard output, or to the file specified by the `-output` (`-o`) option: 297 298 $ echo "Saluton, Mondo" | trans -b -o output.txt :fr 299 300### Translate a File 301 302Instead of using the `-input` option, a [file URI scheme](http://en.wikipedia.org/wiki/File_URI_scheme) (`file://` followed by the file name) can be used as a command-line argument: 303 304 $ trans :fr file://input.txt 305 306**Note**: Brief mode is used when translating from file URI schemes. 307 308### Translate a Web Page 309 310To translate a web page, an http(s) URI scheme can be used as an argument: 311 312 $ trans :fr http://www.w3.org/ 313 314A browser session will open for viewing the translation (via Google Translate's web interface). To specify your web browser of choice, use the `-browser` option: 315 316 $ trans -browser firefox :fr http://www.w3.org/ 317 318### Language Details 319 320Use the `-list` (`-L`) option to view details of one or more languages: 321 322 $ trans -L fr 323 $ trans -L de+en 324 325Some basic information of the language will be displayed: its English name and endonym (language name in the language itself), language family, writing system, canonical Google Translate code and ISO 639-3 code. 326 327### Interactive Translate Shell (REPL) 328 329Start an interactive shell using the `-shell` (or `-interactive`, `-I`) option: 330 331 $ trans -shell 332 333You may specify the source language and the target language(s) before starting an interactive shell: 334 335 $ trans -shell en:fr 336 337You may also change these settings during an interactive session. See **[wiki: REPL](https://github.com/soimort/translate-shell/wiki/REPL)** for more advanced usage of the interactive Translate Shell. 338 339## Usage 340 341For more details on command-line options, see the man page **[trans(1)](https://www.soimort.org/translate-shell/trans.1.html)** or use `trans -M` in a terminal. 342 343``` 344$usage$ 345``` 346 347## Code List 348 349Use `trans -R` or `trans -T` to view the reference table in a terminal. 350 351For more details on languages and corresponding codes, see **[wiki: Languages](https://github.com/soimort/translate-shell/wiki/Languages)**. 352 353$code-list$ 354 355## Wiki 356 357$wiki-home$ 358 359## Reporting Bugs / Contributing 360 361Please review the [guidelines for contributing](https://github.com/soimort/translate-shell/blob/stable/CONTRIBUTING.md) before reporting an issue or sending a pull request. 362 363## Licensing 364 365This is free and unencumbered software released into the public domain. See **[LICENSE](https://github.com/soimort/translate-shell/blob/stable/LICENSE)** and **[WAIVER](https://github.com/soimort/translate-shell/blob/stable/WAIVER)** for details. 366