Guile provides an interface to GNU
gettext for translating
message strings (see Introduction in GNU
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).
gettext is not available, or if Guile was configured
‘--without-nls’, dummy functions doing no translation are
gettext support is available in Guile, the
i18n feature is provided (see Feature Tracking).
Return the translation of msg in domain. domain is
optional and defaults to the domain set through
below. category is optional and defaults to
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
xgettext Program in GNU
(display (gettext "You are in a maze of twisty passages."))
It is conventional to use
G_ as a shorthand for
gettext.23 Libraries can define
G_ in such
a way to look up translations using its specific domain, allowing
different parts of a program to have different translation sources.
(define (G_ msg) (gettext msg "mylibrary")) (display (G_ "File not found."))
G_ 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
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.
gettext above, normal usage is for msg and
msgplural to be literal strings, since
extract them from the source to build a message catalogue. For
(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
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
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"
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
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
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,
#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
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.
gettext might be a bit
G_ is the conventional abbreviation for
gettext. In most other languages, the conventional shorthand is
_. Guile uses
_ is already taken, as it
is bound to a syntactic keyword used by
match, and other macros.