Node:I18N, Previous:GPC Units, Up:Programming

### How to use I18N in own programs

This chapter discusses shortly how to use the Internationalization (I18N) features of GNU Pascal.

#### Prerequisite

You need to have gettext installed. Try to compile `demos/gettextdemo.pas`. Furthermore, you should download a tool named `pas2po` from http://www.gnu-pascal.org/contrib/eike/.

#### The source

We would like to translate the messages provided with this simple example different languages (here: German) without touching the source for each language:

    program Hello1;

    begin
      WriteLn ('Hello, World!');
      WriteLn ('The answer of the questions is: ', 42)
    end.

#### Preparing the source

To do so, we must prepare the source to use gettext:

    program Hello2;

    uses GPC, Intl;

    var Dummy, s: TString;

    begin
      Dummy := BindTextDomain ('hello2', '/usr/share/locale/');
      Dummy := TextDomain ('hello2');
      WriteLn (GetText ('Hello, World!'));
      s := FormatString (GetText ('The answer of the questions is %s'), 42);
      WriteLn (s)
    end.

`BindTextDomain` sets the path to find our message catalogs in the system. This path is system dependent. `TextDomain` tells the program to use this catalog. `GetText` looks up the given string in the catalog and returns a translated string within the current locale settings. `FormatString` replaces some format specifiers with the following argument. `%s` is the first following argument. After this step is done, we do not need to touch the sourcefile any longer. The output of this program is as follows:

    Hello, World!
    The answer of the questions is 42

#### Getting the translatable strings

There are lots of strings in the above example, but only those surrounded with `GetText` should be translated. We use `pas2po hello2.pas -o hello2.po` to extract the messages. The output is:

    # This file was created by pas2po with 'hello2.pas'.
    # Please change this file manually.
    # SOME DESCRIPTIVE TITLE.
    # Copyright (C) YEAR Free Software Foundation, Inc.
    # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
    #
    #, fuzzy
    msgid ""
    msgstr ""
    "Project-Id-Version: PACKAGE VERSION\n"
    "POT-Creation-Date: 2003-04-27 20:48+0200\n"
    "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
    "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
    "Language-Team: LANGUAGE <LL@li.org>\n"
    "MIME-Version: 1.0\n"
    "Content-Type: text/plain; charset=CHARSET\n"
    "Content-Transfer-Encoding: 8bit\n"

    #hello2.pas:10
    msgid "Hello, World!"
    msgstr ""

    #hello2.pas:11
    msgid "The answer of the questions is %s"
    msgstr ""

Now we translate the message ids into German language, and set some needful informations at their appropriate places. The following steps must be repeated for each language we would like to support:

    # This file was created by pas2po with 'hello2.pas'.
    # Copyright (C) 2003 Free Software Foundation, Inc.
    # Eike Lange  <eike@g-n-u.de>, 2003.
    msgid ""
    msgstr ""
    "Project-Id-Version: Hello2 1.0\n"
    "POT-Creation-Date: 2003-04-27 12:00+0200\n"
    "PO-Revision-Date: 2003-04-27 12:06+0200\n"
    "Last-Translator: Eike Lange <eike@g-n-u.de>\n"
    "Language-Team: de <de@li.org>\n"
    "MIME-Version: 1.0\n"
    "Content-Type: text/plain; charset=ISO-8859-1\n"
    "Content-Transfer-Encoding: 8bit\n"

    #hello2.pas:10
    msgid "Hello, World!"
    msgstr "Hallo, Welt!"

    #hello2.pas:11
    msgid "The answer of the questions is %s"
    msgstr "'%s' lautet die Antwort auf die Frage."

Please note that we swapped text and numeric arguments and added some single quotes arround the first argument. We compile the message catalog with `msgfmt -vv hello2.po -o hello2.mo` and install the file `hello2.mo` at `/usr/share/locale/de/LC_MESSAGES/` With a german locale setting, the output should be as follows:

    Hallo, Welt!
    '42' lautet die Antwort auf die Frage.

#### System dependent notes:

The topmost path where message catalogs reside is system dependent:

for DJGPP:
  `GetEnv ('$DJDIR') + '/share/locale'`
for Mac OS X:
  `/usr/share/locale` or `/sw/share/locale`
for Linux, *BSD:
  `/usr/share/locale` or `/usr/local/share/locale`

#### See also

see Gettext, See FormatString, See Intl