Applications access the catalog by line number, so it's very important not to change the line numbers of existing catalog entries. This means that, when you want to add a new string to an existing catalog source, you should always append it to the end of the file--if you put it in the middle of the file, then you change the line number for subsequent strings.
The following tools can help you compile MNLS message catalogs:
exstr(1) | Searches a C source file for literal strings and lists them, or replaces them with MNLS function calls. |
mkmsgs(1) | Creates a message catalog for a particular locale, converting source text lines to the form used by exstr. |
srchtxt(1) | Displays selected strings from a message catalog. |
When a file of strings is ready to be compiled, simply run mkmsgs and put the results in the directory /usr/lib/locale/localename/LC_MESSAGES.
gettxt(1) | Retrieve a string from the catalog. |
lfmt(1) | Retrieve a format string, insert arguments, display to stderr and to system log or textport. |
pfmt(1) | Retrieve a format string, insert arguments, display to stderr. |
To specify the default message catalog to be used by subsequent calls to MNLS functions that reference catalogs, use setcat():
#include <pfmt.h> char *setcat(const char *catalog);catalog is limited to 14 characters, and may contain no character equal to zero or to the ASCII codes for slash (/) or colon (:). (See the setcat(3) reference page.)
setcat() doesn't check to see if the catalog name is valid; it just stores the string for future reference. For an example of use, see the following topic. The catalog indicated by the string must be found in the directory /usr/lib/locale/localename/LC_MESSAGES.
#include <unistd.h> char *gettxt(const char *msgid, const char *defaultStr);msgid is a string containing two fields separated by a colon:
msgfilename:msgnumberThe msgfilename is a catalog name as described previously in the "Specifying MNLS Catalogs". For example, to get message 10 from the MQ catalog, you could use either:
char *str = gettxt("MQ:10", "Hello, world.\n");or
setcat("MQ"); str = gettxt(":10", "Hello, world.\n");
pfmt(stderr, MM_ERROR, "MQ:64:Permission denied");would produce, by default (such as when the Mozambique locale is unavailable),
ERROR: Permission denied.The syntax of pfmt() is
#include <pfmt.h> int pfmt(FILE *stream, long flags, char *format, ... );The flags are used to indicate severity, type, or control details to pfmt(). The format string includes information specifying which message from which catalog to look for. Flag details are discussed in the following section. The format is discussed in the "Format Strings for pfmt()".
output format control | MM_NOSTD, MM_STD |
catalog access control | MM_NOGET, MM_GET |
severity | MM_HALT, MM_ERROR, MM_WARNING, MM_INFO |
action message specification | MM_ACTION |
pfmt() prints messages in the form label:severity:text. Severity is specified in the flags. The text comes from a message catalog (or a default) as specified in the format, and the label is specified earlier by the application.
In the example above, if no label has been set, we get only the output:
ERROR: Permission denied.Typically, an application sets the label once early in its life; subsequent error messages have the label prepended. For example
setlabel("UX:myprog"); ... pfmt(stderr, MM_ERROR, "MQ:64:Permission denied");would produce (by default)
UX:myprog: ERROR: Permission denied.For details, consult the pfmt(3) and setlabel(3) reference pages.
[[catalog:]messagenum:]defaultstringThe catalog field is in the format described in "Specifying MNLS Catalogs". messagenum is the message number in the catalog to use as the format. defaultstring specifies the string to use if the catalog lookup fails for any reason.
An important feature of pfmt() is its ability to refer to format arguments in format-specified order just as printf() does. See "Variably Ordered Referencing of printf() Arguments" for details.
:[catalogname:]msgnumber:catalogname is optional and should be a valid MNLS catalog; msgnumber is the line number in catalogname. If you omit catalogname, the uxsgidesktop catalog is used by default.
You can use these rules to create your own FTR catalog. For example, an entry looks like this:
This entry uses line 7 from the catalog, mycatalog, as the LEGEND for this FTR. If mycatalog is not available, or line 7 is not accessible from mycatalog, "Archive 8mm Tape Drive" is used as the LEGEND.LEGEND :mycatalog:7:Archive 8mm Tape Drive
This entry uses line 7 from the uxsgidesktop catalog, if available. Otherwise, "Archive 8mm Tape Drive" is used.LEGEND :7:Archive 8mm Tape Drive
The next example,
displays line 9 from mycatalog, if available. Otherwise "Eject Tape" is displayed on the menu that pops up when you click an icon that uses this FTR.MENUCMD \'mycatalog:9:Eject Tape\' /usr/sbin/eject /dev/tape
You can internationalize strings in the command part of MENUCMD and CMD rules by using gettxt or any other convenient policy detailed in this section. For example
can be internationalized toCMD OPEN xconfirm -t "Tape tool not available"
In this example, gettxt is invoked to access line 376 from the catalog, mycatalog, and the string returned by gettxt is passed to xconfirm for display. If line 376 from mycatalog is not accessible, then gettxt returns the string "Tape tool not available."CMD OPEN xconfirm -t "'gettxt mycatalog:376 'Tape tool not available''"
For more information about FTRs, see the Indigo Magic Desktop Integration Guide.