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]