HOWTO translate GRASS messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

$Id$


[ Web page: http://grass.itc.it/devel/i18n.php ]

Updating the message catalogs currently only works on 
unix-like systems and requires xgettext.

------------------------------------------------------

REQUIRED SOURCE CODE CHANGES (programming required)

Generally, to support i18N multiple languages,
message strings in GRASS must be modified from

 fprintf ( ..., "...\n", ...);
to
 G_message ( _("...\n"), ...);

Three steps:
1) to replace (see example above:
     a) fprintf (stdout,    with G_message (
     b) fprintf (stderr,    with G_message (

2) to add (see example above):
     the macro _( ) which encapulates the message

3) to be added to file.c header:
     #include "glocale.h"

   This line has to be added to each C file which contains
   user messages, preferably as last #include statement.
   Only, if missing, also add
     #include "gis.h"

NOTE: Also G_warning() and G_fatal_error() need the message
      encapsulation with macro _() but no further changes.

NOTE2: Also the parameters/flags of each module needs the
       macro _().

All these messages strings will be then automatically 
extracted into the message files.

See for example ./vector/v.what.rast/main.c

NOTE3: Such lines
        fprintf (stdout,"\n");
  become simply:
 	G_message ("\n");
  as no translation is needed.

------------------------------------------------------

GENERAL TRANSLATION PROCEDURE (no programming required)

 POT files ----> PO files      ----> MO files
 (original       (translated        (final message file,
  messages)       messages)          used by GRASS programs)


Semi-automated procedure, to perform in this locale/ directory:

   make pot        create grass.pot (containing original messages)

   make update-po  merge new messages into existing *.po files
     [Now translate the messages in the po/*.po files (using kbabel or other editor) ]

   make mo         create the mo files (containing translated messages as binary file)


A convenient software package to translate messages is 'kbabel'.
It permits to enhance it's message database by loading existing
.po files to semi-automate the translation.

Note that GRASS must be configured with '--with-nls' and recompiled
to make use of the translated messages.

There is a file for all library messages and another for all
module messages (this might be split in future).

------------------------------------------------------
DETAILED PROCEDURE :

1. Define/check language settings

   echo $LANG
   echo $LANGUAGE

   Maybe you have to change it (example for Japanese):
   - for bash shell:
       export LANG=ja_JP
       export LANGUAGE=ja_JP
   - for (t)csh shell:
       setenv LANG ja_JP
       setenv LANGUAGE ja_JP

2. CREATE POT FILES
   run
    make pot
    
   This will create
    ./templates/grasslibs.pot
    ./templates/grassmods.pot
       
    
3. CREATE LANGUAGE FILES

   Two cases have to be distinguished:
    a) Messages have not yet been translated to your language.
    b) Some messages have already been translated to your language,
       so you want to merge your efforts into the existing translation.
       
  3.a) First CASE: Messages have not yet been translated to your language.
       No .po file is present for your language in the ./po/ directory.
      
       Run:
        make pot
        make update-po
 
       Copy the generated file from the ./template/ directory
       to the ./po/ directory (for example German language):
        mv ./template/grasslibs.pot ./po/grasslibs_de.po
        mv ./template/grassmods.pot ./po/grassmods_de.po

       Then continue with 4. below.

  3.b) Second CASE: Some messages have already been translated to 
       your language (files present in ./po/ directory), and
       you want to continue with translating new and still
       untranslated messages.

       First we have to merge new messages into existing .po files 
       (which contain already translated messages) as new messages
       might have been added into the GRASS system. 
       To do so, run:
    
       make pot
       make update-po
    
       This will update all existing files in the .po directory.
    


4. TRANSLATE MESSAGES

   In the links section at bottom of this page you find references to the
   'kbabel' and 'poEdit' software to easily translate the message files.
   
   Run 'kbabel' or equivalent program
    kbabel ./po/grasslibs_<LANGUAGE>.po
    kbabel ./po/grassmods_<LANGUAGE>.po

   For example (German):
    kbabel ./po/grasslibs_de.po
    kbabel ./po/grassmods_de.po

   KBABEL: You may load .po files from other projects [see footnote 1]
   
   Pay attention to keep '%s', '\n' and other stuff also 
   in the translated messages!
   
   Please use 'ISO-8859-1' or 'ISO-8859-15' for western languages.  
   See http://en.wikipedia.org/wiki/ISO_8859 for details.
   
   After finishing the translation, save the files.


     
5. CREATE MO FILES

   run
    make mo

   READY.


6. Now recompile, install and run GRASS.
   It should work :-)

7. Send the updated .po files to a GRASS Development Team member.
   If you already updated .c files with G_message("...") as explained
   above, please send diffs against CVS:
   
   cvs diff -u file.c > file.diff
   
   In this case send both the C diff files and the .po files.

   
PLEASE HELP TO TRANSLATE GRASS MESSAGES!

----------------------------------------------

LINKS

- KBabel: http://i18n.kde.org/tools/kbabel/
- poEdit: http://poedit.sourceforge.net/


NOTES

[1] To load existing .po files (eg from older GRASS versions) into
    Kbabel, use
    KBABEL -> SETTINGS -> CONFIGURE DIRECTORY -> PO AUXILIARY

[2] To use QGIS' TS files, you have to convert them to PO format.
    TS files -> PO files converter:
    To translate the .ts files e.g. from QGIS to .po files, 
    use
      http://oss.erdfunkstelle.de/ts2msg/index.shtml

    cd qgis/i18n
    ts2msg utf8 qgis_de.ts
    -> qgis_de.po