When using GNU gettext, each application has its own text domain. This is a unique name, such as kpilot or gawk, that identifies the application. A complete application may have multiple components -- programs written in C or C++, as well as scripts written in sh or awk. All of the components use the same text domain.

To make the discussion concrete, assume we're writing an application named guide. Internationalization consists of the following steps, in this order:

The tools that extract messages from source code pull out all strings enclosed in calls to gettext.

gawk provides the following variables and functions for internationalization:

To use these facilities in your awk program, follow the steps outlined in the previous section, like so:

See the "A Simple Internationalization Example" later in this chapter for an example program showing the steps to create and use translations from awk.

gawk's --gen-po command-line option extracts the messages and is discussed next. After that, printf's ability to rearrange the order for printf arguments at runtime is covered.

Extracting Marked Strings

Rearranging printf Arguments

A possible German translation for this might be:

"%d Zeichen lang ist die Zeichenkette `%s'\n"

The problem should be obvious: the order of the format specifications is different from the original! Even though gettext can return the translated string at runtime, it cannot change the argument order in the call to printf.

To solve this problem, printf format specificiers may have an additional optional element, which we call a positional specifier. For example:

"%2$d Zeichen lang ist die Zeichenkette `%1$s'\n"

Here, the positional specifier consists of an integer count, which indicates which argument to use, and a $. Counts are one-based, and the format string itself is notincluded. Thus, in the following example, string is the first argument and length(string) is the second:

$ gawk 'BEGIN {
>     string = "Dont Panic"
>     printf _"%2$d characters live in \"%1$s\"\n",
>                         string, length(string)
> }'
10 characters live in "Dont Panic"

If present, positional specifiers come first in the format specification, before the flags, the field width, and/or the precision.

Positional specifiers can be used with the dynamic field width and precision capability:

$ gawk 'BEGIN {
>    printf("%*.*s\n", 10, 20, "hello")
>    printf("%3$*2$.*1$s\n", 20, 10, "hello")
> }'
hello
hello

NOTE: When using * with a positional specifier, the * comes first, then the integer position, and then the $. This is somewhat counterintuitive.

NOTE: There are some pathological cases that gawk may fail to diagnose. In such cases, the output may not be what you expect. It's still a bad idea to try mixing them, even if gawk doesn't detect it.

Although positional specifiers can be used directly in awk programs, their primary purpose is to help in producing correct translations of format strings into languages different from the one in which the program is first written.

awk Portability Issues

As written, it won't work on other versions of awk. However, it is actually almost portable, requiring very little change:

Following are the translations:

#: guide.awk:4
msgid "Don't Panic"
msgstr "Hey man, relax!"

#: guide.awk:5
msgid "The Answer Is"
msgstr "Like, the scoop is"

The next step is to make the directory to hold the binary message object file and then to create the guide.mo file. The directory layout shown here is standard for GNU gettext on GNU/Linux systems. Other versions of gettext may use a different layout:

$ mkdir en_US en_US/LC_MESSAGES

The msgfmt utility does the conversion from human-readable .po file to machine-readable .mo file. By default, msgfmt creates a file named messages. This file must be renamed and placed in the proper directory so that gawk can find it:

$ msgfmt guide-mellow.po$ mv messages en_US/LC_MESSAGES/guide.mo

Finally, we run the program to test it:

$ gawk -f guide.awk
Hey man, relax!
Like, the scoop is 42
Pardon me, Zaphod who?

If the two replacement functions for dcgettext and bindtextdomain (see "awk Portability Issues" earlier in this chapter) are in a file named libintl.awk, then we can run guide.awk unchanged as follows:

$ gawk --posix -f guide.awk -f libintl.awk
Don't Panic
The Answer Is 42
Pardon me, Zaphod who?