5.40 National Language Support Functions

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 The ‘begin’ and ‘end’ special handlers). 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.

Built-in Function: string bindtextdomain (string domain, string dirname) ¶

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.

Built-in Function: string dgettext (string domain, string msgid) ¶

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.

Built-in Function: string dngettext (string domain, string msgid, string msgid_plural, number n) ¶

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.

Library Function: string textdomain (string domain) ¶

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"

Library Function: string gettext (string msgid) ¶

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.

Library Function: string ngettext (string msgid, string msgid_plural, number n) ¶

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.