ChinVoc Vocabulary Trainer Logo
© 2006 Tobias Elzeflag german
Download Contributions and Examples Screenshots

What is ChinVoc?

ChinVoc is a vocabulary trainer for learning Chinese. One can input word lists containing Chinese signs (both traditional and simplified), Latin transcription (Pinyin), and the English translation. The program can be used to train the word lists in various ways.

ChinVoc is composed of two independent parts: Training words and generating new word lists. Training can be performed even on systems without Chinese input methods. Therefore, the program is suited for users without much experience in Eastern Asian typing methods.


ChinVoc is written in a manner that is as platform independent as possible, i.e. it should run under any common operating system, and there is a good prospect of longevity of this software so that you can use it even in many years on very different systems. There are different requirements for training and generating word lists.


For training you need a web browser which is capable of JavaScript and DHTML. Almost all modern web browsers meet these demands. I tried out Mozilla Firefox 1.x, Opera 8.x, Konqueror 3.x, and Camino (MacOS X). Some screenshots show how the training looks like under different browsers and operating systems.

Microsoft Internet Explorer will probably not work since at the moment of writing (early 2006) its latest version is technically hopelessly outdated. Moreover, it violates many of the W3C Standards.

If you do not have a web browser that fulfils these requirements, the easiest solution is to download firefox which is available for free for many operating systems.

In addition to that, Chinese fonts have to be installed on your operating system. This may be the case under your operating system even if you never worked with Chinese before. If you do not see all Chinese characters or pinyin letters correctly, check the installation medium of your operating system if there is Chinese language support.

You can try out easily if your browser is working. Just click on this example and choose Go. If the training starts, ChinVoc is working on your system.

Input a new word list

A Chinese input method has to be installed on your system, unless you have the opportunity just to copy and paste the Chinese characters (which is working if someone else typed them before). For most operating systems (e.g. Linux, MacOS X, or MS Windows) you can optionally install Chinese language support from your system installation media.

Microsoft Windows

If you installed ChinVoc using the msi file from the download section, no further software is needed. Otherwise, see the subsection for other operating systems below.

Other Operating Systems

If you want to generate a new word list for later training, you need Perl (Version >= 5.8.0) to be installed on your system. Perl is installed on most operating systems by default. An exception is Microsoft Windows. But for this operating system (and also others) you can get Perl for free from ActiveState. Just click on the link and follow the instructions.


Go to the download section, download the program, preferably the version for your operating system, if there is one, and follow the instructions of the installer.


A .deb package is provided for Linux which is tested on Ubuntu but should work on all Debian based distributions. If you do not use a Debian based distribution, either use conversion like alien or download the sources.

Microsoft Windows

A Windows Installer (msi) file is provided. If you have Windows 95, 98, or NT4, you need to get Windows installer first, e.g. from here for Windows 9x and from here for NT4. For all later versions of Windows it works out of the box.

Other Operating Systems

If there is no version for your OS, just get the source code. There is no need of compilation, it runs out of the box provided you have Perl in a version not less than 5.8.0.



The training files are simple html files. Just open them in your browser (if your standard browser fulfils the requirements stated above, you may even double click them). Then choose your preferred training conditions and run the training. That's all. If you make a mistake, the respective word is added to the end of the training set and then prompted once more.

Here you can check a simple example containing the members of a Chinese family as training words: family.htm. Input method input (i.e. not multiple choice) ignores capitalization and matches any consecutive sequence of single words of your entry. If you train Pinyin you can either type the accented letters for the tones or the respective syllable immediately followed by a single digit representing the tone.


Mode: choose between multiple choice or input from keyboard
display: what is displayed for training
prompt: what you have to input for training
MC Options: number of choices in multiple choice mode
Permutations: how often the randomly permuted word list is repeated

Input a new word list

To input a new word list, use a text editor of your choice (under Windows e.g. notepad), choose UTF-8 as encoding and type every new entry into a single line. Every line has to be organized in the following manner: At first the Chinese characters, after this the Pinyin transcription, and finally the English translation. These three parts are seperated by the following character: |

The following file is an example of such an input list: family.chinvoc. Here is an example of two entries:

您好!|nín hǎo|Hello!

As you can see, Pinyin can be typed either with numbers immediately following the syllable (numbers 1 to 4 indicate the tone, first line; type v instead of ) or directly with the accented letters (second line). You can save your file under any name, but it is suggested to use the extension .chinvoc. (Windows users: If you work with notepad as an editor, it may want to enforce .txt as filename extension. In order to prevent this, type the filename in double quotes: "myfile.chinvoc").

For backward compatibility reasons with version 1.0, ChinVoc accepts not only the tone number following the whole syllable but also the tone number following the respective vowel, e.g. ha3o instead of hao3. However, this should not be used anymore. Important: In order to determine the tone positions, ChinVoc needs to separate the Pinyin syllables. Therefore leave spaces or other word boundaries between your Pinyin syllables.

If you installed ChinVoc using the msi file, you can now just double click myfile.chinvoc. If you didn't use an installer, make sure that is in your search path or copy the file to your current working directory. If your word list is saved to "mylist.chinvoc" then call mylist.chinvoc

In both cases mylist.chinvoc will be converted to an html file that can be used for training (see above).

Command Line Options

If ChinVoc is invoked in a shell you can pass parameters to the program that affect the training file or provide details about ChinVoc. The parameter --help informs about these options and shows their syntax:

 ./ --help

Usage: ./ [options] inputfile
Convert an input file filename to an html file containing the new vocabulary.
Output file name: inputfile.htm

  -cpmessage    add potential copyright violation message
  -logo         add sourceforge logo
  -message=m    add message m (string)
                e.g. -message="fill the gaps with the right entries"
  -convert      -convert inputfile [inputfile1 [inputfile2 [...]]]
                convert (in place) inputfile(s) from version 1.0
                to format of higher versions, i.e. shift the numbers
                in pinyin entries to the end of the syllables;
                keeps the 1.0 files under filenames inputfile.old
  -h, --help    display this usage information and exit
  -v, --version display version number and exit

User Contributions

If you think that this project is useful and if you use ChinVoc, feel free to send me your self generated new word lists. I can publish them on this site so that all ChinVoc users can profit from them. This needs not to be in English, any other language will do as well. It will be especially nice if you typed the vocabulary of some standard Chinese teaching book that many people know. My email address:

tobias-elze (at)

Have fun!