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