gawk: Programmer i18n
1
1 13.3 Internationalizing 'awk' Programs
1 ======================================
1
1 'gawk' provides the following variables for internationalization:
1
1 'TEXTDOMAIN'
1 This variable indicates the application's text domain. For
1 compatibility with GNU 'gettext', the default value is
1 '"messages"'.
1
1 '_"your message here"'
1 String constants marked with a leading underscore are candidates
1 for translation at runtime. String constants without a leading
1 underscore are not translated.
1
1 'gawk' provides the following functions for internationalization:
1
1 'dcgettext(STRING [, DOMAIN [, CATEGORY]])'
1 Return the translation of STRING in text domain DOMAIN for locale
1 category CATEGORY. The default value for DOMAIN is the current
1 value of 'TEXTDOMAIN'. The default value for CATEGORY is
1 '"LC_MESSAGES"'.
1
1 If you supply a value for CATEGORY, it must be a string equal to
11 one of the known locale categories described in ⇒Explaining
gettext. You must also supply a text domain. Use 'TEXTDOMAIN'
1 if you want to use the current domain.
1
1 CAUTION: The order of arguments to the 'awk' version of the
1 'dcgettext()' function is purposely different from the order
1 for the C version. The 'awk' version's order was chosen to be
1 simple and to allow for reasonable 'awk'-style default
1 arguments.
1
1 'dcngettext(STRING1, STRING2, NUMBER [, DOMAIN [, CATEGORY]])'
1 Return the plural form used for NUMBER of the translation of
1 STRING1 and STRING2 in text domain DOMAIN for locale category
1 CATEGORY. STRING1 is the English singular variant of a message,
1 and STRING2 is the English plural variant of the same message. The
1 default value for DOMAIN is the current value of 'TEXTDOMAIN'. The
1 default value for CATEGORY is '"LC_MESSAGES"'.
1
1 The same remarks about argument order as for the 'dcgettext()'
1 function apply.
1
1 'bindtextdomain(DIRECTORY [, DOMAIN ])'
1 Change the directory in which 'gettext' looks for '.gmo' files, in
1 case they will not or cannot be placed in the standard locations
1 (e.g., during testing). Return the directory in which DOMAIN is
1 "bound."
1
1 The default DOMAIN is the value of 'TEXTDOMAIN'. If DIRECTORY is
1 the null string ('""'), then 'bindtextdomain()' returns the current
1 binding for the given DOMAIN.
1
1 To use these facilities in your 'awk' program, follow these steps:
1
1 1. Set the variable 'TEXTDOMAIN' to the text domain of your program.
1 This is best done in a 'BEGIN' rule (⇒BEGIN/END), or it can
1 also be done via the '-v' command-line option (⇒Options):
1
1 BEGIN {
1 TEXTDOMAIN = "guide"
1 ...
1 }
1
1 2. Mark all translatable strings with a leading underscore ('_')
1 character. It _must_ be adjacent to the opening quote of the
1 string. For example:
1
1 print _"hello, world"
1 x = _"you goofed"
1 printf(_"Number of users is %d\n", nusers)
1
1 3. If you are creating strings dynamically, you can still translate
1 them, using the 'dcgettext()' built-in function:(1)
1
1 if (groggy)
1 message = dcgettext("%d customers disturbing me\n", "adminprog")
1 else
1 message = dcgettext("enjoying %d customers\n", "adminprog")
1 printf(message, ncustomers)
1
1 Here, the call to 'dcgettext()' supplies a different text domain
1 ('"adminprog"') in which to find the message, but it uses the
1 default '"LC_MESSAGES"' category.
1
1 The previous example only works if 'ncustomers' is greater than
1 one. This example would be better done with 'dcngettext()':
1
1 if (groggy)
1 message = dcngettext("%d customer disturbing me\n",
1 "%d customers disturbing me\n",
1 ncustomers, "adminprog")
1 else
1 message = dcngettext("enjoying %d customer\n",
1 "enjoying %d customers\n",
1 ncustomers, "adminprog")
1 printf(message, ncustomers)
1
1 4. During development, you might want to put the '.gmo' file in a
1 private directory for testing. This is done with the
1 'bindtextdomain()' built-in function:
1
1 BEGIN {
1 TEXTDOMAIN = "guide" # our text domain
1 if (Testing) {
1 # where to find our files
1 bindtextdomain("testdir")
1 # joe is in charge of adminprog
1 bindtextdomain("../joe/testdir", "adminprog")
1 }
1 ...
1 }
1
1 ⇒I18N Example for an example program showing the steps to
1 create and use translations from 'awk'.
1
1 ---------- Footnotes ----------
1
1 (1) Thanks to Bruno Haible for this example.
1