Translate C.a.R. to other Languages

Since I recently got more and more requests from far away countries, I thought I should describe the localization features of C.a.R. in this Wiki. First of all, the textual user interaction of C.a.R. consists of the following parts.

  • The GUI localization of the menus, the dialogs, the error messages, the keyboard shortcuts, the non-visual commands etc. This help is contained in the “” files described below.
  • The context help, accessible through the help button in the program. All help texts are gathered in one file “info.txt”.
  • The welcome message displayed in the program with the “News” button. This is a short file “version.txt”.
  • The HTML documentation and examples, contained in many files on my Web server for English and German, and distributed with the program in the Windows installer, and the archive for other operating systems.

I describe each of these items in the following.

In any case, please mail me before you start working. It might be that some other person is already working on the same language. It does not make sense to do the work twice. Moreover, I can only include one of the translations into the program.

Translating the GUI

To translate the GUI you need access to the “*.properties” files contained in the program archive. If you are not experienced with Java, I can send you this file and include your translation into the archive for you. But it is better, if you follow the following steps. You will then be able to test your translation yourself. I cannot test foreign translations.

First of all, install the Java development kit from Sun. You find it on Sun's site. Go to Downloads and install the Java development kit as administrator.

Then create a new directory for your work. Download the latest version of the program archive “zirkel.jar” from the C.a.R. homepage.

You need to open a command line. In case, you never used a command line under Windows, ask someone to explain it to you, or search the Net for details. You need to change the directory to the the one containing the archive, and unpack the archive with the command

jar -xf zirkel.jar

At this point, you can run the program from the command line, using

java Zirkel

Now you need any good text editor of your choice (but do not use Word or some other text processor). I suggest you use notepad under Windows. Linux or Mac users will know what to use.

You should work on a copy of the properties file. Of course, you can simply backup “” and work on that file, which contains the English program version as default language. But it is better to find your local two letter country code. Have a look at ISO 3166 to find your code.

For the following example commands, I assume you work under Windows and in Aphganisthan (country code af).

cd rene\zirkel\docs
copy ZirkelProperties_af.txt
notepad ZirkelProperties_af.txt

You then have to do the work and translate all strings after the “=” sign in each line. Do not touch the parts before the “=”! You can simply delete the first block of lines, since this part should be taken from the default properties file. Note that any string not contained in your translation will be taken from the default file.

You may change the program name to something nice in your language, but I suggest keeping the English name. If you create a new homepage in your language, you can leave that part too, but make sure to link to the orgininal homepage. So users can find new program versions.

Save the properties file in your local encoding. Aphghanistan does not have an own encoding. So I assume for this example it is using Arabic, which is CP1256 (under Windows). Then the file must be translated to the ASCII format, using the following command.

native2ascii -encoding CP1256 ZirkelProperties_af.txt >

You then change to the archive directory and test your translation with the following command. The “-l” parameter makes sure, your language is really used.

java Zirkel -l af

To pack the archive, use the command

del zirkel.jar
jar -cfm zirkel.jar META-INF/MANIFEST.MF .

To test the archive, use

java -jar zirkel.jar

Translating the Context Help

The context help in English is contained in the file “rene\zirkel\docs\info.txt”. Like above you copy the file to some “info_af.txt” and work on the file.

You can leave the file in your local encoding, if you are adding this encoding to the properties file. For the German context help, I had to add the following two properties to “”.


Refer to the GUI section above to learn how to add these properties.

The context help file uses sections of texts. Each new section starts with a section name, which is a label behind a dot, like “.line”. Do not change these labels. The next line after the label contains related sections. Do not change this line too!

Everything else can be changed and translated. You need not take care of line formatting, since paragraphs are reformatted for the display. Paragraphs are separated by empty lines. If a paragraph starts with a blank, all lines of that paragraph will be indented.

Extracting HTML from the Context Help

From Version 6.1 on, it is possible to extract HTML pages from the context help. For each topic (section of text starting with “.topic”), the program will generate a HTML page with the same name, including links to related topics. A list of topics, and a list of keywords will also be generated. I have added an “.index” topic in the German and English files to get a starting point for the HTML pages.

You find an example is the English and the German documentation on the homepage of C.a.R..

To extract the help pages use the following command

java -jar zirkel.jar rene.helptohtml.Translator sourcefile encoding

You need to replace “sourcefile” with your context help file, e.g. “info_af.txt”, and “encoding” with the encoding of your file, e.g. “UTF-8”. If it is your local encoding use “default”. You should copy “zirkel.jar” and “info_xx.txt” to a new directory. The output files of the program will be placed in the current directory. So, start the command in that directory.

You need two more files “header.dat” and “footer.dat”. These are the frames for the HTML files, including the body tags. An example is

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html xmlns="">

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Language" content="de" />


for “header.dat” and


for “footer.dat”. Of course, you may also link to stylesheets here.

Keywords can be marked with double underscores.


To enforce your editor to keep keywords with spaces in one line, you can use the paragraph letter as in


This letter is replaced by spaces everywhere. A list of keywords is extracted from this with links to all topics, where the keywords appear. Capitalization of the keyword does not matter.

Do not use any HTML command or any text that might confuse HTML. The output will always be in UTF-8. So there is no need to encode local characters. The < and > letters are relaced properly by HTML equivalents.

To add images to the HTML output, use the following commands

//image filename

//image- filename
Start of new paragraph

//image+ filename
Start of new paragraph

The last two versions create floating images on the left and right of the starting paragraphs.

Note, that the help viewer in the program cannot display keywords or images currently.

Translating the Version Information

This should be straightforward. Simply copy the file “version.txt” to “version_af.txt” (if “af” is your two letter country code), and translate. Here is a good place to leave a link to your homepage. Use your local encoding for this file and observe the changes necessary in the properties file as mentioned above.

The HTML Files

For this, you need a webspace. In case of emergency, I might host your pages. But you will not be able to edit them directly. So it is better to use some of the ample space available now on free hosts.

Do not offer the program for download. Link to the C.a.R. homepage instead. Of course, you can offer examples etc.

If you need any help, contact me or the C.a.R. community.

tutorials/translate.txt · Last modified: 2007/04/13 14:08 by rene
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki