==================================================================
How to make a Native Language Support application using VDKBuilder
==================================================================
Copyright 2000, The VDK Team
Report bugs and comments about this short tutorial to:
Mario Motta mmotta@guest.net

GENERAL
-------
With version 1.2.4 VDKBuilder come with a NLS support. However support 
is implemented in a way that it takes care to write the code to 
support NLS on gui files side only (thus those files that are overwritten 
by builder and out of user control).
The remaining part of the NLS stuff is under user responsibility 
that must write his own code to support NSL and take care of use 
gettextize, editing configure.in, aclocal.m4, POTFILES.in, po.* 
files and other necessary activities.
At this end i wrote this notes that should help the new user in
constructing a nls application with VDKBuilder. Notes are written
as a check-list and all actions should be made in the presented order.
Where applicable i have put also explanatory notes together with
the actions to do.
I have taken a simple hello program as tutorial base, however the
procedure is applicable also to more complex examples.
So let's assume the user will construct a simple hello program that
shows a form with a label and two buttons, one labeled "Hello" and 
the other "Close". Clicking on Hello button label will show the 
famous phrase "Hello world" and clicking on "Close" button quits the
application. So the phrases to translate are:
"Hello world", "Hello" and "Close".

1. CONSTRUCTING HELLO PROGRAM WITH VDKBuilder
---------------------------------------------
First action to do is to initiate a new project named "hello" and build a 
program following above guidelines and setting on "project options" 
the NLS support checkbutton to true. When you finished and checked
that the program runs ok save the project.
Taking a look to hello_gui.cc you will see that all button captions
are defined using a _("caption") notation. Looking at file header you 
will see also the defines for macro _(str) and N_(str), this defines
depends on some other defines such as ENABLE_LS and HAVE_GNOME. Those
definitions drive gettext operations. VDKBuilder wrote for you these
definitions and use the _("") or N_("") notation but other work 
should be prepared in background until see hello program prompts
translated in your language. Below notes guide you to the target.

2. USING AUTOCONF/AUTOMAKE
--------------------------
In order to localize your program (thus make it translatable in other 
languages) you have to use Autoconf/Automake VDKBuilder support.
Once you are sure that your hello program works well use 
Autoconf/Automake menu and run Autogen (you will notice that you must
run it twice in order to have other menus enabled). This will prepare
all necessary files to construct hello using automake features.
Now an important point: from now when you will use Autogen again
remember to choose to DO NOT REGENERATE, so answer always "no" to the
prompt that ask you if you want regenerate some files. The reason
is simple: you are going to manually modify some files to prepare
NLS support (configure.in, Makefile.am and acconfig.h) and you want
avoid to overwrite your changes. However even if you make the mistake
to answer yes you can recover your modified files from a backup copy
made as configure.in.old, etc...

3. PREPARING YOUR PROGRAM TO BE USED WITH GETTEXT
-------------------------------------------------
The first thing to do is to "gettexttize" the directory where hello
project is contained. At this end we will use gettextize program that
will prepare two subdirs: intl and po that will contain files for nsl
operations.
So open an xterm and:
$ cd <where hello project is>
$ gettextize -f .
answer yes to the program prompt, if any.

gettextize will add to your dir following file:
ABOUT-NLS
and will create ./po and ./intl subdirs with all necessary files.
Once gettextize has finished it will leave you with the following message:
"You should update your own `aclocal.m4' by adding the necessary
macro packages gettext.m4, lcmessage.m4 and progtest.m4 from
the directory `/aclocal'"
aclocal.m4 is a file prepared by autogen and that now should be updated with
above macro packages.
You should know where aclocal packages are, generally they are either on
/usr/share/aclocal or /usr/local/share/aclocal. Here we assume that are 
located into /usr/share/aclocal. So append to your aclocal.m4 macro packages 
contained into above suggested m4 files.

$ cat /usr/share/aclocal/gettext.m4 > aclocal.m4
$ cat /usr/share/aclocal/lcmessage.m4 > aclocal.m4 
$ cat /usr/share/aclocal/progtest.m4 > aclocal.m4

now update your project dir with aclocal program

$ aclocal

4. EDITING AUTOCONF/AUTOMAKE FILES
----------------------------------
Now is necessary update manually some autoconf/automake generated files
into your project dir.

4a) Editing ./configure.in
==========================
Edit configure.in inserting these lines
below AC_CANONICAL_HOST

dnl -------------------------
dnl Gettext stuff
ALL_LINGUAS="en <your prefix>"
AM_GNU_GETTEXT
dnl --------------------------

substitute <your prefix> with your languages prefix, as an example
could be:
ALL_LINGUAS="en it fr de es"
thus meaning that program should be localized in en-english,it-italian,
fr-french,de-german and es-spanish

now insert these lines below AC_SUBST(CXXFLAGS)

dnl ------------------------------------------------------------------------
dnl Set the location of the locale messages to be used in main.cc
dnl This will substitute HELLO_LOCALE_DIR in config.h (from acconfig.h).
if test "x$prefix" = "xNONE"; then
  HELLO_LOCALE_DIR=$ac_default_prefix/share/locale
else
  HELLO_LOCALE_DIR=$prefix/share/locale
fi
AC_DEFINE_UNQUOTED(HELLO_LOCALE_DIR, "$HELLO_LOCALE_DIR")

AC_DEFUN(FC_EXPAND_DIR, [
        $1=$2
        $1=`(
                test "x$prefix" = xNONE && prefix="$ac_default_prefix"
                test "x$exec_prefix" = xNONE && exec_prefix="${prefix}"
                eval echo \""[$]$1"\"
        )`
])
dnl ----------------------------------------------------------------------

now change line:
AC_OUTPUT(Makefile)
to read:
AC_OUTPUT(Makefile po/Makefile.in intl/Makefile)

Now save configure.in

4b) Editing Makefile.am
=======================
Edit Makefile.am and change line:

SUBDIRS = .
to read:
SUBDIRS = po intl

Again save Makefile.am

4c) Editing acconfig.h
======================
Edit acconfig.h and add these lines:
#undef ENABLE_NLS
#undef HAVE_CATGETS
#undef HAVE_GETTEXT
#undef HAVE_LC_MESSAGES
#undef HAVE_STPCPY
#undef NETBUILDER_LOCALE_DIR

Again save acconfig.h

5.  CREATING po/POTFILES.in file
--------------------------------
POTFILES.in file is used to know which source files should be scanned
to search translatable strings.
Create and save  po/POTFILES.in putting a source file for each line:
#============================
hello.cc
hello_gui.cc
#===========================
this file will be used by autogen to create the correct Makefile into po
subdirectory.

6. RUNNING AUTOGEN AND MAKE
---------------------------
Using Autoconf/Automake menu run:
Make distclean to remove old files
Autogen (recall DO NOT REGENERATE)
Make
You should receive following messages:
Makefile.am:20: it in `ALL_LINGUAS' but po/it.po does not exist
Makefile.am:20: en in `ALL_LINGUAS' but po/en.po does not exist
make[2]: *** No rule to make target `en.po', needed by `en.gmo'.  Stop.
that are normal since constructing above files will be the next step.
If you look into po subdir you will see file "hello.pot" that is the 
template file obtained from source scanning.

7. TRANSLATING INTO LOCALE LANGUAGES
------------------------------------
Copy hello.pot into en.po and whichever other prefix you
defined into ALL_LINGUAS macro into configure.in.
So with the xterm :
$ cd po
$ cp hello.pot en.po
$ cp hello.pot <your prefix>.po

Normally en.po do not need to be translated since all strings should be
as in sources. What you translate are it.po and companions.
Each po file appear in this format:
#: hello_gui.cc:36
msgid "hello Main Form"
msgstr ""
where the first line shows which source line were scanned
"msgid" shows original string and "msgstr" what you have to translate.
Edit to read:
#: hello_gui.cc:36
msgid "hello Main Form"
msgstr "<your translation>"
and so on for all msgid/msgstr pairs into the file.
NOTE:
emacs editor recognizes po files and provides an easy way to edit this
file with many nice features. If you use emacs just add to your .emacs
file these lines:
(setq auto-mode-alist
      ( cons '("\\.pox?\\'" . po-mode) auto-mode-alist))
(autoload 'po-mode "po-mode")

8. PREPARING YOUR SOURCE CODE TO NLS
------------------------------------
VDKBuilder support nls on the gui files side only, other sources
are under your responsibility so you have to prepare them to support
nls.

8a) Editing hello.cc
====================
At file header insert:
//-------------------------------
/*
hello Plain VDK Application
Main unit implementation file:hello.cc
*/
#if HAVE_CONFIG_H
#include <config.h>
#endif
#if !HAVE_GNOME
#if ENABLE_NLS
#include <libintl.h>
#define _(str) gettext(str)
#define N_(str) str
#else
#define _(str) str
#define N_(str) str
#endif
#endif
//--------------------------------
#include <hello.h>

(you will notice that same header is shown also in hello_gui.cc)

now edit main() to read:
/*
main program
*/
int main (int argc, char *argv[])
{
#if ENABLE_NLS
  bindtextdomain(PACKAGE,HELLO_LOCALE_DIR);
  textdomain(PACKAGE);
#endif
// makes application
HelloApp app(&argc, argv);
// runs application
app.Run();
return 0;
}

8b) Changing project options
=============================
Use "project -> options" menu and edit the "defines field" to read:
-DHAVE_CONFIG_H=1 -DHAVE_GNOME=1


9. BUILDING NSL AWARE APPLICATION
---------------------------------
The first build should be made using an xterm and Makefile generated by
automake:
$ make
this will make hello program and prepare translated files
# make install
this will install translated files to appropriate usr/share/locale
directory so it can be correctly bound by bindtextdomain().

$ hello
you should see that hello now shows button captions translated into your
language.

10. ADDING MORE TRANSLATABLE STRINGS
------------------------------------
If you click on hello button you will see still "hello world" in english
not in your language as you expect.
This is because "hello world" was not marked for translation yet.
As a general rule each string with _("a string") notation is marked for
translation and will be parsed to be added to po files.
Most likely you have established a signal response function on hello button
clicked:
//signal response method
bool
HelloForm::OnhelloButtonClick(VDKObject* sender)
{
  label0->Caption = "Hello world";
  return true;
}
Now change to read:
label0->Caption = _("Hello world");

Adding a translatable string need to update po files and make-install
again:
$ cd po
$ make update-po

Edit <your prefix>.po and translate "hello world"

# make install

Now
$ hello
should show "Hello world" translated if you click on hello button.

11. FINAL NOTES
---------------
a. As long as you do not add any translatable string, directly into source
code or indirectly adding widgets with captions to gui, you can continue
to use builder normal making-project facilities. But if you want see your
newly added translatable strings you have to repeat the steps:
$ cd po
$ make update-po
translate
# make install


b. A good further reading is GNU gettext manual that you can find at
http://www.gnu.org