Next: Syslog Interface, Previous: Sockmaps, Up: Library [Contents][Index]
The National Language Support functions allow you to write your scripts in such a way, that any textual messages they display are automatically translated to your native language, or, more precisely, to the language required by your current locale.
This section assumes the reader is familiar with the concepts of program
internationalization and localization. If not, please
refer to The Purpose of GNU
gettext
in GNU gettext manual, before reading further.
In general, internationalization of any MFL script
follows the same rules as described in the GNU gettext manual.
First of all, you select the program message domain, i.e. the
identifier of a set of translatable messages your script contain.
This identifier is then used to select appropriate translation.
The message domain is set using textdomain
function. For the
purposes of this section, let’s suppose the domain name is
‘myfilter’. All NLS functions are provided in the
nls module, which you need to require prior to using
any of them.
To find translations of textual message to the current locale, the
underlying gettext
mechanism will look for file
dirname/locale/LC_MESSAGES/domainname.mo,
where dirname is the message catalog hierarchy name,
locale is the locale name, and domainname is the name of
the message domain. By default dirname is
/usr/local/share/locale, but you may change it using
bindtextdomain
function. The right place for this initial
NLS setup is in the ‘begin’ block (see begin/end).
To summarize all the above, the usual NLS setup will look like:
require nls begin do textdomain("myfilter") bindtextdomain("myfilter", "/usr/share/locale"); done
For example, given the settings above, and supposing the environment
variable LC_ALL
is set to ‘pl’, translations will be looked
in file /usr/share/locale/pl/LC_MESSAGES/myfilter.mo.
Once this preparatory work is done, you can request each message to
be translated by using gettext
function, or _
(underscore) macro. For example, the following statement will produce
translated textual description for ‘450’ response:
tempfail 450 4.1.0 _("Try again later")
Of course it assumes that the appropriate myfile.mo file
already exists. If it does not, nothing bad happens: in this case the
macro _
(as well as gettext
function) will simply
return its argument unchanged, so that the remote party will get the
textual message in English.
The ‘mo’ files are binary files created from ‘po’ source
files using msgfmt
utility, as described in Producing Binary MO Files in GNU
gettext manual. In turn, the format of ‘po’ files is described
in The Format of PO Files in GNU gettext manual.
This function sets the base directory of the hierarchy containing message catalogs for a given message domain.
domain is a string identifying the textual domain. If it is not empty, the base directory for message catalogs belonging to domain domain is set to dirname. It is important that dirname be an absolute pathname; otherwise it cannot be guaranteed that the message catalogs will be found.
If domain is ‘""’, bindtextdomain
returns the
previously set base directory for domain domain.
The rest of this section describes the NLS functions supplied in the nls module.
dgettext
attempts to translate the string msgid into the
currently active locale, according to the settings of the textual
domain domain. If there is no translation available,
dgettext
returns msgid unchanged.
The dngettext
functions attempts to translate a text string
into the language specified by the current locale, by looking up the
appropriate singular or plural form of the translation in a message
catalog, set for the textual domain domain.
See Additional functions for plural forms in GNU gettext utilities, for a discussion of the plural form handling in different languages.
The textdomain
function sets the current message domain to
domain, if it is not empty. In any case the function returns
the current message domain. The current domain is ‘mailfromd’
initially. For example, the following sequence of textdomain
invocations will yield:
textdomain("") ⇒ "mailfromd" textdomain("myfilter") ⇒ "myfilter" textdomain("") ⇒ "myfilter"
gettext
attempts to translate the string msgid into the
currently active locale, according to the settings of the current textual
domain (set using textdomain
function). If there is no
translation available, gettext
returns msgid unchanged.
The ngettext
functions attempts to translate a text string
into the language specified by the current locale, by looking up the
appropriate singular or plural form of the translation in a message
catalog, set for the current textual domain.
See Additional functions for plural forms in GNU gettext utilities, for a discussion of the plural form handling in different languages.
Next: Syslog Interface, Previous: Sockmaps, Up: Library [Contents][Index]