12.69 text.gettext - Localized messages

Module: text.gettext ¶

This module provides utilities to deal with localized messages. The API is compatible to GNU’s gettext, and the messages are read from *.po and *.mo files, so that you can use the GNU gettext toolchain to prepare localized messages. However, the code is written from scratch by Alex Shinn and doesn’t depend on GNU’s gettext library.

This implementation extends GNU’s gettext API in the following ways:

• It can read from multiple message files in cascaded way, allowing applications to share a part of message files.
• It supports multiple locale/domain simultaneously.

SRFI-29 (see srfi.29 - Localization) provides another means of message localization. A portable program may wish to use SRFI-29, but generally text.gettext is recommended in Gauche scripts because of its flexibility and compatibility to existing message files.

Gettext-compatible API

Function: textdomain domain-name :optional locale dirs cdir cached? lookup-cached? ¶

{text.gettext} Sets up the default domain and other parameters for the application. The setting affects to the following gettext call.

Domain is a string or list of strings specifying the domain (name of .mo or .po files) as in C gettext. You can pass #f as domain-name just to get the default domain accessor procedure. You can alo pass multiple domains to domain-name.

(textdomain '("myapp" "gimp"))  ; search 1st myapp, then gimp
(gettext "/File/Close")         ; "Close" from gimp unless overridden

Locale is a string or list of strings in the standard Unix format of LANG[_REGION][.ENCODING]. You can also pass a list of locales to specify fallbacks.

(textdomain "myapp" '("ru" "uk"))  ; search 1st Russian then Ukranian,
(gettext "Hello, World!")          ; which are somewhat similar

Dirs is the search path of directories which should hold the LOCALE/CDIR/ directories which contain the actual message catalogs. This is always appended with the system default, e.g. "/usr/share/locale", and may also inherit from the GETTEXT_PATH colon-delimited environment variable.

Cdir is the category directory, defaulting to either the LC_CATEGORY environment variable or the appropriate system default (e.g. LC_MESSAGES). You generally won’t need this.

Cached? means to cache individual messages, and defaults to #t.

Lookup-cached? means to cache the lookup dispatch generated by these parameters, and defaults to #t.

Textdomain just passes these parameters to the internal make-gettext, and binds the result to the global dispatch used by gettext. You may build these closures manually for convenience in using multiple separate domains or locales at once (useful for server environments). See the description of make-gettext below.

Textdomain returns an accessor procedure which packages information of the domain. See make-gettext below for the details.

Function: gettext msg-id ¶

{text.gettext} Returns a translated message of msg-id. If there’s no translated message, msg-id itself is returned.

Function: ngettext msg-id :optional msg-id2 num ¶

{text.gettext} Similar to gettext, but it can be used to handle plural forms. Pass a singular form to msg-id, and plural form to msg-id2. The num argument is used to determine the plural form. If no message catalog is found, msg-id is returned when num is 1, and msg-id2 otherwise.

Function: bindtextdomain domain dirs ¶

{text.gettext} Sets the search path of domain domain to dirs, which may be just a single directory name or a list of directory names.

Function: dgettext domain msg-id ¶

Function: dcgettext domain msg-id locale ¶

{text.gettext} Returns a translated message of msg-id in domain. Dcgettext takes locale as well.

Low-level flexible API

The following procedure is more flexible interface, on top of which the gettext-compatible APIs are written.

Function: make-gettext :optional domain locale dirs gettext-cached? lookup-cached? ¶

{text.gettext} Creates and returns an accessor procedure, which encapsulates methods to retrieve localized messages.

The meaning of arguments are the same as textdomain above. Indeed, textdomain just calls make-gettext, and later it binds the result to the global parameter. If you wish to have multiple independent domains within a single program, you can call make-gettext directly and manage the created accessor procedure by yourself.

(define my-gettext (make-gettext "myapp"))
(define _ (my-gettext 'getter))
(_ "Hello, World!")