
Using national language support (NLS) in FreeType
=================================================

21. 1. 1998
Erwin Dieterich


1) Intro
2) Using gettext (user's view)
3) Using gettext (programmer's view)
4) Using gettext (maintainer's view)
5) How can I switch off NLS, I don't need/want it.


Only Unix NLS  using gettext() is covered here.  If  you are able to
help  with  internationalization   (i18n)  for  different  operating
systems, please contact the FreeType mailing lists.



1) Intro

If a program is to be used  by people who are not fluent speakers of
English, the first thing they will ask for is communication in their
native tongue.  If  someone tries to support NLS  in a program using
only #ifdef and alike, chances  are good that this will get nowhere.
gettext() is a possible way to help.  Only minimal extra programming
effort is needed; the translations are completely separated from the
program and it  is not necessary to recompile a  program if you need
the messages  in a different language.   If you'd like  to know more
about gettext(),  I recommend reading the GNU  gettext tools manual,
version 0.10.27 by Ulrich Drepper, Jim Meyering and Francois Pinard.

Currently supported languages are:

  German (de)
  French (fr)

Currently supported programs in test/ are:

  ftlint 
  ftdump
  fterrtest


2) Using gettext (user's view)

Using gettext as an end user  is very simple.  If someone (you?) has
installed FreeType  on your computer  and did everything  right, you
can simply issue an "export LANG=<language id>" in your Bourne shell
or "setenv LANG=<language id>" if  you are using a csh.  That's all.
If you want/need to switch  back to English, just use "export LANG="
or "setenv LANG=".  <language id> is a two character code describing
your language:  de=German, fr=French etc.   Every supported language
has its own <language id>.po  file in the po/ directory of FreeType.
If your language is not there you should consider contributing a new
translation.   Just email  me.  Here  is a  transcript of  what this
"export LANG=<language id>" does:

    test > ftlint 24 furiosot.ttf
    furiosot.ttf: Could not find or open file.
    FreeType error message: OS/2 table missing.

    test > export LANG=de
    test > ftlint 24 furiosot.ttf
    furiosot.ttf: Datei konnte nicht gefunden oder geffnet werden.
    FreeType Fehlermeldung: OS/2-Tabelle fehlt.

    test > export LANG=
    test > ftlint 24 furiosot.ttf
    furiosot.ttf: Could not find or open file.
    FreeType error message: OS/2 table missing.

Now does this look nice?  But  what if nothing happens, once you set
LANG?  Here are some hints:

First: Is your language really supported?   If it is: you need to be
sure  that you have  gettext() installed  (if you  are sitting  at a
Linux box, chances are very good that you have).  If you've compiled
FreeType by yourself and nothing strange happened, then your version
of FreeType has already NLS compiled in, as this is the default.  If
you  didn't forget  to install  the translation  files in  the right
places  ("make  install"  should   be  enough,  but  you  need  root
permissions as these files are installed somewhere in /usr/local) --
good luck :-)


3) Using gettext (programmer's view)

If you intend to use NLS in  your program, you need to change just a
few bits  here and there.  In  this small documentation  file I only
describe how NLS is enabled  in the programs that come with FreeType
in test/.  If you'd like to add NLS to other programs using FreeType
as well, have a look at the installation files of FreeType: probably
you can use these files as a model.

Every string  that should be  translated needs gettext()  around it.
So

  Message("Usage: %s fontname[.ttf|.ttc]\n\n", execname);

becomes

  Message(gettext("Usage: %s fontname[.ttf|.ttc]\n\n"), execname);


Yes, it is  that simple.  Then you need  to initialize gettext.  You
need this in the header section of your file:

    #include "ft_conf.h"
    #ifdef HAVE_LIBINTL_H
    #include <libintl.h>
    #endif

    #ifndef HAVE_LIBINTL
    #define gettext(x) (x)
    #endif

and this at the very beginning of your main program:

    #ifdef HAVE_LIBINTL
      setlocale(LC_ALL, "");
      bindtextdomain("freetype", LOCALEDIR);
      textdomain("freetype");
    #endif


That's all.  Just have a look at fterror.c in test/.


4) Using gettext (maintainer's view)

I am too lazy today :-)  Just ask me if something isn't clear.


5) How can I switch off NLS, I don't need/want it.

Just say "configure --disable-nls" and recompile FreeType.


If  you  have  any   questions  or  comments  regarding  this  short
introduction  to  NLS   &  FreeType,  feel  free  to   email  me  at
Erwin.Dieterich.ED@Bayer-AG.de
