6.25.6 Gettext Support

Guile provides an interface to GNU gettext for translating message strings (see Introduction in GNU gettext utilities).

Messages are collected in domains, so different libraries and programs maintain different message catalogues. The domain parameter in the functions below is 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. When gettext support is available in Guile, the i18n feature is provided (see Feature Tracking).

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 (see Locales).

Normal usage is for msg to be a literal string. xgettext can extract those from the source to form a message catalogue ready for translators (see Invoking the xgettext Program in GNU gettext utilities).

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

_ is a commonly used shorthand, an application can make that an alias for gettext. Or a library can make a definition that uses its specific domain (so an application can change the default without affecting the library).

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

_ is also a good place to perhaps strip disambiguating extra text from the message string, as for instance in How to use gettext in GUI programs in GNU gettext utilities.

Scheme Procedure: ngettext msg msgplural n [domain [category]]

C Function: scm_ngettext (msg, msgplural, n, domain, category)

Return the translation of msg/msgplural in domain, with a 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 (see Locales).

msg is the singular form, and msgplural the plural. When no translation is available, msg is used if n = 1, or msgplural otherwise. When translated, the message catalogue can have a different rule, and can have more than two possible forms.

As per gettext above, normal usage is for msg and msgplural to be literal strings, since xgettext can extract them from the source to build a message catalogue. For example,

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

(done 1) -| 1 file processed
(done 3) -| 3 files processed

It’s important to use ngettext rather than plain gettext for plurals, since the rules for singular and plural forms in English are not the same in other languages. Only ngettext will allow translators to give correct forms (see Additional functions for plural forms in GNU gettext utilities).

Scheme Procedure: textdomain [domain]

C Function: scm_textdomain (domain)

Get or set the default gettext domain. When called with no parameter the current domain is returned. When called with a parameter, domain is set as the current domain, and that new value 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 without a directory the current setting is returned. When called with a directory, directory is set for domain and that new setting 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 by generating a config file) and set that for its domain. This ensures the catalogue 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 Unix/POSIX system the iconv program can list all available encodings.)

When called without an encoding the current setting is returned, or #f if none yet set. When called with an encoding, it is set for domain and that new setting returned. 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 file, 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.