doc gettext

[Kevin Ryde]

I'm looking at the text below to expand what's in the guile reference
manual for gettext.  It adds some examples and some bits of advice.

I'm a bit unsure about bind-textdomain-codeset.  Thinking about it, if
Guile gets its own notion of coding systems or whatever in the future
then I'm wondering if that function might become obsolete, or even
actively harmful.  It does some good now, but maybe some strong
warning against possible future change is needed.




5.20 Support for Internationalization
=====================================

Guile provides an interface to GNU `gettext' for translating message
strings (*note Introduction: (gettext)Introduction.).

   Message domains allow messages from different programs or libraries
to be kept separate.  A domain is just a string (it becomes part of the
message catalog filename).

   When `gettext' is not available, or if Guile was configured
`--without-nls', dummy functions doing no translation are provided.

 -- Scheme Procedure: gettext msg [domain [category]]
 -- C Function: scm_gettext (msg, domain, category)
     Return the translation of MSG in DOMAIN.  DOMAIN is optional and
     defaults to the domain set through `textdomain' below.  CATEGORY
     is optional and defaults to `LC_MESSAGES'.

     If a program has many messages, a shorthand can be created.  `_'
     is usual for this, and is recognised by `xgettext' (*note Invoking
     the `xgettext' Program: (gettext)xgettext Invocation.).

          (define _ gettext)
          (display (_ "You are in a maze of twisty passages."))

     In a library the same can be done, but usually a domain should be
     given explicitly, so it will still work if an application makes
     itself as the default.

          (define (_ msg) (gettext msg "mylibrary"))
          (display (_ "File not found."))

     Such a shorthand is also a good place to perhaps strip
     disambiguating extra text from the message string, as per for
     instance *Note How to use `gettext' in GUI programs: (gettext)GUI
     program problems.

 -- Scheme Procedure: ngettext msg msg_plural n [domain [category]]
 -- C Function: scm_ngettext (msg, msg_plural, n, domain, category)
     Return the translation of MSG/MSG_PLURAL in DOMAIN, with the
     plural form chosen appropriately for the number N.  DOMAIN is
     optional and defaults to the domain set through `textdomain'
     below.  CATEGORY is optional and defaults to `LC_MESSAGES'.  For
     example,

          (define (done n)
            (format #t (ngettext "~a file processed\n"
                                 "~a files processed\n" n)
                       n))

     It's important to use `ngettext' for plurals, to allow translators
     to give the proper forms for various N in other languages.

 -- Scheme Procedure: textdomain [domain]
 -- C Function: scm_textdomain (domain)
     Get or set the default gettext domain.  When called with DOMAIN,
     it is set as the default, and that new value returned.  When called
     with no parameter the current domain is returned.  For example,

          (textdomain "myprog")
          => "myprog"

 -- Scheme Procedure: bindtextdomain domain [directory]
 -- C Function: scm_bindtextdomain (domain, directory)
     Get or set the directory under which to find message files for
     DOMAIN.  When called with a DIRECTORY, DIRECTORY is set for DOMAIN
     and that new setting returned.  When called without a DIRECTORY
     the current setting is returned.  For example,

          (bindtextdomain "myprog" "/my/tree/share/locale")
          => "/my/tree/share/locale"

     When using Autoconf/Automake, an application should arrange for the
     configured `localedir' to get into the program (by substituting,
     or generating a config file) and set that for its domain.  This
     ensures the catalog can be found even when installed in a
     non-standard location.

 -- Scheme Procedure: bind-textdomain-codeset domain [encoding]
 -- C Function: scm_bind_textdomain_codeset (domain, encoding)
     Get or set the text encoding to be used by `gettext' for messages
     from DOMAIN.  ENCODING is a string, the name of a coding system,
     for instance "8859_1".  (On a GNU system the `iconv' program can
     list all available encodings.)

     When called with an ENCODING, it is set for DOMAIN and that new
     setting returned.  When called without an ENCODING the current
     setting is returned, or `#f' if none yet set.  For example,

          (bind-textdomain-codeset "myprog")
          => #f
          (bind-textdomain-codeset "myprog" "latin-9")
          => "latin-9"

     The encoding requested can be different from the translated data,
     messages will be recoded as necessary.  But note that when there
     is no translation `gettext' returns its MSG unchanged, ie.
     without any recoding.  For that reason source message strings are
     best as plain ASCII.

     Currently Guile has no understanding of multi-byte characters, and
     string functions won't recognise character boundaries in multi-byte
     strings.  An application will at least be able to pass such strings
     through to some output though.  Perhaps this will change in the
     future.