Warning: This is the manual of the legacy Guile 2.2 series. You may want to read the manual of the current stable series instead.
Previous: Accessing Locale Information, Up: Internationalization [Contents][Index]
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).
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.
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).
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
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.
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.
Previous: Accessing Locale Information, Up: Internationalization [Contents][Index]