This tutorial will help you to translate Coccinella to a new language or to update an existing language catalog. Note that the instructions are optimized to unix-like systems.

1. Check out the 'tools' module from CVS:

   cvs -d:pserver:anonymous@coccinella.cvs.sourceforge.net:/cvsroot/coccinella login
   cvs -z3 -d:pserver:anonymous@coccinella.cvs.sourceforge.net:/cvsroot/coccinella co -P tools

2. In tools/i18n/ you will find several tools that assist in making and analyzing message catalogs. Make sure the scripts are executable before you use them.

3. Make sure you are in the coccinella source tree by 'cd coccinella/'. Find the tools/i18n/template.tcl script and move it to coccinella/ or use its full path when executing it.

   If you already have an existing language catalog, named xx.msg, you update it using:

   ./template.tcl msgs/en.msg xx -targetfile msgs/xx.msg -sourcedir . -printreferencestrings 1

   You can play around with the switches and see what they do. Read the sources of template.tcl for the definite guide. If you do not already have a catalog, then do:

   ./template.tcl msgs/en.msg xx -sourcedir . -printreferencestrings 1

   Both scripts produce a templete catalog 'template-xx.msg' in your current directory. Move it to the msg/ directory for testing. Make sure you do not overwrite any existing catalog you want to save:

   mv template-xx.msg msgs/xx.msg

4. Now you need an editor that has the capabilities to handle utf-8 encoding because that is what is used throughout. There are some scripts below that can transform a text file back and forth, but safest is to use an editor. Alternatively, use the 'iconv' command on unix/linux. On linux there is an editor named Kate which seems good. Be sure it uses utf-8, menu: Tools/Encoding/Unicode (utf8).

5. Finally, it is up to you to load up with caffeine to suit your mood, and start authoring. The syntax for each entry in a message catalog is:

   ::msgcat::mcset langCode key ?translatedString?

   Add the 'translatedString' if missing, and do translate if exists. Be sure that the 'translatedString' is enclosed in "{" and "}".

   Note that some of the menu strings, typically of the form mMenuEntry, have an ampersand "&" in their text string. This says that the character following it will be underlined and the "&" be removed from display text. The underlined character corresponds to a keyboard shortcut for that entry. You are free to pick the underlined character which suits your language yourself, but remember that each character may be underlined only once in a menu.

6. Some of the strings contain one or more "%s". These will be replaced by variables when the string is displayed. You need to see the code if you want to know the replacement variable.

   In some cases your language may have a different grammar than English, and there may be situations where the order of the replacement variables must change. In such situations you need to add positional codes. An example discribes it best:

   {This is the %s and %s attempt} FIRST SECOND 
   This is the FIRST and SECOND attempt 
   
   {This is the %2$s and %1$s attempt} FIRST SECOND 
   This is the SECOND and FIRST attempt

   You just replace "%s" with "%#$s" where # is an integer describing the position.

7. Your new language catalog will be loaded automatically.

8. Some components and packages have their own catalogs inside coccinella/msgs/components, see the README-msgs-components file inside this directory. The process is essentially repeated for each directory.