GNU Info

(gawk.info)Programmer i18n

---

Next: Translator i18n Prev: Explaining gettext Up: Internationalization

---

Enter node , (file) or (file)node

Internationalizing `awk' Programs
=================================

   `gawk' provides the following variables and functions for
internationalization:

`TEXTDOMAIN'
     This variable indicates the application's text domain.  For
     compatibility with GNU `gettext', the default value is
     `"messages"'.

`_"your message here"'
     String constants marked with a leading underscore are candidates
     for translation at runtime.  String constants without a leading
     underscore are not translated.

`dcgettext(STRING [, DOMAIN [, CATEGORY]])'
     This built-in function returns the translation of STRING in text
     domain DOMAIN for locale category CATEGORY.  The default value for
     DOMAIN is the current value of `TEXTDOMAIN'.  The default value
     for CATEGORY is `"LC_MESSAGES"'.

     If you supply a value for CATEGORY, it must be a string equal to
     one of the known locale categories described in Note: GNU
     `gettext'.  You must also supply a text
     domain.  Use `TEXTDOMAIN' if you want to use the current domain.

     *Caution:* The order of arguments to the `awk' version of the
     `dcgettext' function is purposely different from the order for the
     C version.  The `awk' version's order was chosen to be simple and
     to allow for reasonable `awk'-style default arguments.

`bindtextdomain(DIRECTORY [, DOMAIN])'
     This built-in function allows you to specify the directory where
     `gettext' looks for `.mo' files, in case they will not or cannot
     be placed in the standard locations (e.g., during testing).  It
     returns the directory where DOMAIN is "bound."

     The default DOMAIN is the value of `TEXTDOMAIN'.  If DIRECTORY is
     the null string (`""'), then `bindtextdomain' returns the current
     binding for the given DOMAIN.

   To use these facilities in your `awk' program, follow the steps
outlined in Note: GNU `gettext', like so:

  1. Set the variable `TEXTDOMAIN' to the text domain of your program.
     This is best done in a `BEGIN' rule (Note: The `BEGIN' and `END'
     Special Patterns.), or it can also be done via the `-v'
     command-line option (Note: Command-Line Options.):

          BEGIN {
              TEXTDOMAIN = "guide"
              ...
          }

  2. Mark all translatable strings with a leading underscore (`_')
     character.  It _must_ be adjacent to the opening quote of the
     string.  For example:

          print _"hello, world"
          x = _"you goofed"
          printf(_"Number of users is %d\n", nusers)

  3. If you are creating strings dynamically, you can still translate
     them, using the `dcgettext' built-in function.

          message = nusers " users logged in"
          message = dcgettext(message, "adminprog")
          print message

     Here, the call to `dcgettext' supplies a different text domain
     (`"adminprog"') in which to find the message, but it uses the
     default `"LC_MESSAGES"' category.

  4. During development, you might want to put the `.mo' file in a
     private directory for testing.  This is done with the
     `bindtextdomain' built-in function:

          BEGIN {
             TEXTDOMAIN = "guide"   # our text domain
             if (Testing) {
                 # where to find our files
                 bindtextdomain("testdir")
                 # joe is in charge of adminprog
                 bindtextdomain("../joe/testdir", "adminprog")
             }
             ...
          }


   Note: A Simple Internationalization Example, for an
example program showing the steps necessary to create and use
translations from `awk'.