11.9 srfi.29 - Localization

Module: srfi.29 ¶

This module implements the message localization mechanism defined in SRFI-29.

In fact, this module consists of two submodules, srfi.29.bundle and srfi.29.format. The module srfi.29 extends both submodules. It is because srfi-29’s definition of the format procedure is incompatible to Gauche’s native format (thus Common Lisp’s format) in the handling of ~@* directive.

So I splitted the module into two, srfi.29.format which contains srfi-29’s format, and srfi.29.bundle which contains the rest ("bundle" API). If a program wishes a complete compatibility of srfi-29, use srfi.29 module, which overrides Gauche’s native format. If a program just wants srfi-29’s "bundle" API, but wants to keep Gauche’s format, use srfi.29.bundle.

A localization feature is also provided by text.gettext module (see text.gettext - Localized messages), which is a preferable way of message localization in Gauche. This module is provided mainly for porting code that uses srfi-29 features.

Bundle specifier

A bundle specifier is an arbitrary list of symbols, but typically it takes the form like:

(package language country details …)

Where package specifies the software package, language and country specifies language and country code, and details gives other informations like encoding.

The values for the default bundle specifier can be obtained by the following parameters.

Parameter: current-language ¶

Parameter: current-country ¶

Parameter: current-locale-details ¶

[SRFI-29]{srfi.29} The current-language and current-country parameters keep the ISO 639-1 language code and ISO 3166-1 country code respectively, both as symbols. The current-locale-details keeps a list of auxiliary local informations, such as encodings.

These parameters are initialized if LANG environment variable is set in the form of lang_country.encoding format. For example, if the LANG setting is ja_JP.eucJP, those parameters are ja, jp, and (eucjp), respectively. If LANG is C or undefined, the default values are en, us, and (), respectively.

Bundle preparation

Function: declare-bundle! bundle-specifier association-list ¶

[SRFI-29]{srfi.29} Put the association list of template key (symbol) and the locale-specific message (string) into the bundle database, with bundle-specifier as the key.

Gauche currently supports only in-memory bundle database. That is, you have to call declare-bundle! within the application in order to lookup the localized messages.

Function: save-bundle! bundle-specifier ¶

Function: load-bundle! bundle-specifier ¶

[SRFI-29]{srfi.29} Since Gauche doesn’t support persistent bundle database yet, these procedures does nothing and returns #f. (It is still conforming behavior of srfi-29).

Retrieving localized message

Function: localized-template package-name message-template-name ¶

[SRFI-29]{srfi.29} Retrieves localized message, associated with a symbol message-template-name in the package package-name.

Extended format procedure

Function: format format-string args ¶

[SRFI-29]{srfi.29} SRFI-29 extends SRFI-28’s format procedure spec (which supports ~a, ~s, ~% and ~~ directives), in order to support argument repositioning.

A directive ~N@*, where N is an integer or can be omitted, causes the next directive to retrieve a value from N-th optional argument. The referenced value isn’t consumed, and won’t affect the processing of subsequent directives.

Although SRFI-28 spec is compatible to Gauche’s native format (see Output), this SRFI-29 extension isn’t. Specifically, the ~N@* directive of Gauche’s format changes the argument pointer to points N-th optional argument, thus it affects all the subsequent arguments.

Because of this incompatibility, this function is defined in a separate module, srfi.29.format. If you use srfi.29, which extends srfi.29.bundle and srfi.29.format, the format procedure will be overridden by srfi-29’s format in your module. If you want to keep Gauche’s native format, use srfi.29.bundle only.