doc/I18N-HOWTO

   1 Autoconf/I18n-ify HelloWorld HOW-TO
   2 -----------------------------------
   3
   4 Authors:
   5         Kenneth Christiansen <kenneth at gnu dot org>
   6         Thomas Vander Stichele <thomas at apestaart dot org>
   7
   8 Help from: Bruno Haible <bruno at clisp dot org>
   9
  10 Disclaimer:
  11         Kenneth last used autoconf 2.52 and automake 1.4p5 to test this guide.
  12         Thomas last used autoconf 2.52 and automake 1.5 to test this guide.
  13         We would like you to let us know if you have different versions of
  14         these tools and things don't work out the same way.
  15         No authors of any autotools were harmed during the making of this guide.
  16
  17 In this article we are going to explain how to turn a simple
  18 Hello World application with a standard Makefile into an autotools-
  19 and I18N-enabled tree up to the point where it can be distributed.
  20
  21 Our existing helloworld.c file looks like the following:
  22
  23 #include <stdio.h>
  24
  25 int main (void) {
  26   printf ("Hello, world!\n");
  27 }
  28
  29 1. First we create a source tree :
  30
  31    /                        - This is the top level directory
  32    /src/                    - Here the source will end up.
  33
  34    and place the helloworld.c file in the src/ dir
  35
  36 2. If your program has not been autoconf-enabled yet, you can
  37    create configure.scan (which is a good starting point for configure.ac)
  38    and rename it to configure.ac
  39
  40         autoscan   # creates configure.scan
  41         mv configure.scan configure.ac
  42
  43    Now edit configure.ac and make some changes.
  44    You can remove everything after AC_INIT, we'll be using AM_INIT_AUTOMAKE
  45    to pass on variables.
  46
  47    Add the lines
  48      PACKAGE=helloworld
  49      VERSION=0.0.1
  50      AM_INIT_AUTOMAKE($PACKAGE, $VERSION)
  51    to configure.in, just after AC_INIT
  52
  53    Change AC_CONFIG_HEADER to AM_CONFIG_HEADER as well.
  54
  55    If you have an empty AC_CONFIG_FILES macro, then comment that, or automake
  56    will fail in the next step.
  57
  58    Finally, add Makefile to the AC_OUTPUT macro by changing that
  59    line to read
  60      AC_OUTPUT(Makefile)
  61
  62    NOTE: configure.ac used to be called configure.in
  63
  64 3. We add some files that automake does not make but are necessary
  65    to adhere to GNU standards.
  66
  67    touch NEWS README AUTHORS ChangeLog
  68
  69    These two files need to be created to satisfy automake
  70
  71    touch config.h.in Makefile.am
  72
  73    We will create Makefile.am later on.
  74
  75 4. To add some basic files (like COPYING, INSTALL, etc..)
  76    we run automake in the toplevel directory.
  77
  78    automake --add-missing --gnu
  79
  80 5. After that we do the big i18n trick :-), also in the toplevel
  81    directory.
  82
  83    intltoolize                  # bring in the perl helper scripts
  84                                 # and our Makefile.in.in for the po directory
  85
  86 6. Run autoheader which will create config.h.in
  87
  88         autoheader # create config.h.in
  89
  90 7. Now, open up configure.in and make some modifications.
  91
  92     The gettext macros need to be added after the initial checks.
  93     Putting them after the checks for library functions is a good idea.
  94
  95     IT_PROG_INTLTOOL(0.26)
  96
  97     AM_GNU_GETTEXT([external])          # Only one of these two macro calls
  98     AM_GLIB_GNU_GETTEXT                 # is needed to set up your project
  99
 100     ALL_LINGUAS="da nl"                 # Internationalization, means there is
 101                                         # a .po file for danish and dutch.
 102
 103     AC_OUTPUT(
 104         Makefile
 105         src/Makefile
 106         intl/Makefile
 107         po/Makefile.in
 108     )
 109
 110     IT_PROG_INTLTOOL checks if a good enough intltool is available.
 111     Please require the latest intltool that exists. Intltool releases
 112     are pretty stable and often only contains bugfixes.
 113
 114     AM_GNU_GETTEXT adds native language support to automake, together
 115     with a compile option.
 116
 117     AM_GNU_GETTEXT will check for additional required functions and
 118     programs and will finally create po/POTFILES during configure.
 119
 120     Instead of AM_GNU_GETTEXT you can use AM_GLIB_GNU_GETTEXT, which
 121     will do a few less things than AM_GNU_GETTEXT, but does more than
 122     enough for what intltool needs to work.
 123
 124     You do NOT need to use both AM_GNU_GETTEXT and AM_GLIB_GNU_GETTEXT
 125     together though. Only one of them will suffice.
 126
 127     The text domain is identified by PACKAGE.  We will need to add a few
 128     functions later on to helloworld.c that will use this #define'd variable.
 129
 130     Also, this will be the base filename for all your translation files,
 131     so make sure you choose a unique one.
 132
 133 8.
 134     Now add the add the supported languages to po/LINGUAS:
 135
 136     da nl
 137
 138     NOTE: These used to be in configure.{in,ac} in the ALL_LINGUAS
 139     variable. This is deprecated since gettext 0.11
 140
 141 9.  Run
 142        aclocal
 143      to make sure that the necessary autoconf and automake macros
 144      are inserted in aclocal.m4
 145
 146      Run
 147        autoconf
 148      to create the configure script.
 149
 150 10. install the gettext.h file (since gettext 0.11) and include it:
 151
 152     #include "gettext.h"
 153     #define _(String) gettext (String)
 154
 155 11. Now add the following to helloworld.c
 156
 157     #include <locale.h>
 158     #include "gettext.h"
 159     #define _(String) gettext (String)
 160     /* includes used by original program here */
 161
 162     int main (void)
 163     {
 164
 165             setlocale (LC_ALL, "");
 166             bindtextdomain (PACKAGE, LOCALEDIR);
 167             textdomain (PACKAGE);
 168
 169             /* Original Helloworld code here */
 170     }
 171
 172     If you use GNOME or GTK+ the setlocale sentence shouldn't be needed
 173
 174     We also substitute all strings we want to be translated with
 175     _("original string") to make sure that gettext is run on the strings.
 176     So the printf now looks like
 177
 178       printf (_("Hello, world!\n"));
 179
 180 12. We create src/Makefile.am (from which Makefile.in and Makefile will be
 181     generated)
 182
 183     INCLUDES = -I$(top_srcdir) -I$(includedir) \
 184                -DLOCALEDIR=\""$(datadir)/locale"\"
 185
 186     bin_PROGRAMS = helloworld
 187
 188     helloworld_SOURCES = helloworld.c
 189     noinst_HEADERS = i18n-support.h
 190
 191 13. Now we create the following toplevel Makefile.am
 192
 193      SUBDIRS = src po
 194
 195 14. Go into the directory po/ and create POTFILES.in
 196     This file should contain a list of all the files in your distribution
 197     (starting from the top, one level above the po dir) that contain
 198     strings to be internationalized.
 199
 200     For the helloworld sample, it would contain
 201     src/helloworld.c
 202
 203     Run
 204       intltool-update --pot
 205
 206     Run
 207       intltool-update --maintain
 208     to see if you are missing files that contain marked strings.
 209     You should consider adding these to POTFILES.in
 210
 211
 212 15. Now we start making a Danish and Dutch translation
 213
 214     msginit --locale=da
 215     msginit --locale=nl
 216
 217     intltool-update da
 218     intltool-update nl
 219
 220     edit and update da.po and nl.po
 221     (The respective translations are "Hej verden" and "Hallo wereld")
 222
 223 16. Now we can compile.  We will test it later, so we will install it in
 224     a temporary location.
 225     Close your eyes and type
 226       ./configure --prefix=/tmp/helloworld && make
 227     in the toplevel directory. :-)
 228
 229 17. To test if it works, you have to install the package.
 230     Run
 231       make install
 232     in the toplevel directory.
 233
 234 18. Now set the environment variable LC_ALL to your preferred language :
 235       export LC_ALL=nl_NL
 236       /tmp/helloworld/bin/helloworld
 237       export LC_ALL=da_DK
 238       /tmp/helloworld/bin/helloworld
 239
 240     And if all goes well, the string should be translated in the two languages.
 241
 242 19. To finish it all up, run
 243       make dist
 244     to create a distributable tarball containing your internationalized
 245     program.
 246
 247 20. Exercises :
 248     - add another language
 249