Notes on the messages implementation.

prepared by Benjamin Kosnik (bkoz@redhat.com) on August 8, 2001

1. Abstract

The std::messages facet implements message retrieval functionality equivalent to Java's java.text.MessageFormat .using either GNU gettext or IEEE 1003.1-200 functions.

2. What the standard says

The std::messages facet is probably the most vaguely defined facet in the standard library. It's assumed that this facility was built into the standard library in order to convert string literals from one locale to the other. For instance, converting the "C" locale's const char* c = "please" to a German-localized "bitte" during program execution.
22.2.7.1 - Template class messages [lib.locale.messages]
This class has three public member functions, which directly correspond to three protected virtual member functions. The public member functions are:

catalog open(const string&, const locale&) const

string_type get(catalog, int, int, const string_type&) const

void close(catalog) const

While the virtual functions are:

catalog do_open(const string&, const locale&) const

-1- Returns: A value that may be passed to get() to retrieve a message, from the message catalog identified by the string name according to an implementation-defined mapping. The result can be used until it is passed to close(). Returns a value less than 0 if no such catalog can be opened.

string_type do_get(catalog, int, int, const string_type&) const

-3- Requires: A catalog cat obtained from open() and not yet closed. -4- Returns: A message identified by arguments set, msgid, and dfault, according to an implementation-defined mapping. If no such message can be found, returns dfault.

void do_close(catalog) const

-5- Requires: A catalog cat obtained from open() and not yet closed. -6- Effects: Releases unspecified resources associated with cat. -7- Notes: The limit on such resources, if any, is implementation-defined.

3. Problems with "C" messages: thread safety, over-specification, and assumptions.

A couple of notes on the standard.

First, why is messages_base::catalog specified as a typedef to int? This makes sense for implementations that use catopen, but not for others. Fortunately, it's not heavily used and so only a minor irritant.

Second, by making the member functions const, it is impossible to save state in them. Thus, storing away information used in the 'open' member function for use in 'get' is impossible. This is unfortunate.

The 'open' member function in particular seems to be oddly designed. The signature seems quite peculiar. Why specify a const string& argument, for instance, instead of just const char*? Or, why specify a const locale& argument that is to be used in the 'get' member function? How, exactly, is this locale argument useful? What was the intent? It might make sense if a locale argument was associated with a given default message string in the 'open' member function, for instance. Quite murky and unclear, on reflection.

Lastly, it seems odd that messages, which explicitly require code conversion, don't use the codecvt facet. Because the messages facet has only one template parameter, it is assumed that ctype, and not codecvt, is to be used to convert between character sets.

It is implicitly assumed that the locale for the default message string in 'get' is in the "C" locale. Thus, all source code is assumed to be written in English, so translations are always from "en_US" to other, explicitly named locales.

4. Design and Implementation Details

This is a relatively simple class, on the face of it. The standard specifies very little in concrete terms, so generic implementations that are conforming yet do very little are the norm. Adding functionality that would be useful to programmers and comparable to Java's java.text.MessageFormat takes a bit of work, and is highly dependent on the capabilities of the underlying operating system.

Three different mechanisms have been provided, selectable via configure flags:

A new, standards-conformant non-virtual member function signature was added for 'open' so that a directory could be specified with a given message catalog. This simplifies calling conventions for the gnu model.

The rest of this document discusses details of the GNU model.

The messages facet, because it is retrieving and converting between characters sets, depends on the ctype and perhaps the codecvt facet in a given locale. In addition, underlying "C" library locale support is necessary for more than just the LC_MESSAGES mask: LC_CTYPE is also necessary. To avoid any unpleasantness, all bits of the "C" mask (ie LC_ALL) are set before retrieving messages.

Making the message catalogs can be initially tricky, but become quite simple with practice. For complete info, see the gettext documentation. Here's an idea of what is required:

5. Examples

More information can be found in the following testcases:

6. Unresolved Issues

7. Acknowledgments

Ulrich Drepper for the character set explanations, gettext details, and patient answering of late-night questions, Tom Tromey for the java details.

8. Bibliography / Referenced Documents

Drepper, Ulrich, GNU libc (glibc) 2.2 manual. In particular, Chapters "7 Locales and Internationalization"

Drepper, Ulrich, Thread-Aware Locale Model, A proposal. This is a draft document describing the design of glibc 2.3 MT locale functionality.

Drepper, Ulrich, Numerous, late-night email correspondence

ISO/IEC 9899:1999 Programming languages - C

ISO/IEC 14882:1998 Programming languages - C++

Java 2 Platform, Standard Edition, v 1.3.1 API Specification. In particular, java.util.Properties, java.text.MessageFormat, java.util.Locale, java.util.ResourceBundle. http://java.sun.com/j2se/1.3/docs/api

System Interface Definitions, Issue 7 (IEEE Std. 1003.1-200x) The Open Group/The Institute of Electrical and Electronics Engineers, Inc. In particular see lines 5268-5427. http://www.opennc.org/austin/docreg.html

GNU gettext tools, version 0.10.38, Native Language Support Library and Tools. http://sources.redhat.com/gettext

Langer, Angelika and Klaus Kreft, Standard C++ IOStreams and Locales, Advanced Programmer's Guide and Reference, Addison Wesley Longman, Inc. 2000. See page 725, Internationalized Messages.

Stroustrup, Bjarne, Appendix D, The C++ Programming Language, Special Edition, Addison Wesley, Inc. 2000