Message catalogs

#include <x/messages.H>

x::messages msgcat(x::messages::create(l, "app"));

x::messages is a reference to a reference-counted object that provides access to internationalized message catalogs created by the gettext library. Its get() method returns strings using the encoding specified by the given locale. x::wmessages is an analogous reference whose get() method returns wide strings.

x::const_messages and x::const_wmessages are references to constant message catalog access objects. At this time, none of the referenced objects' method modify the object, so the constant references are equivalent to their non-constant version, in terms of functionality.

gettextmsg()

The gettextmsg() function is a convenience function for creating localized messages in a stream-like fashion:

std::cout << x::gettextmsg(msgcat->get("Window size: %1% rows, %2% columns"),
                      nrows, ncols) << std::endl;

The first argument to gettextmsg() is typically a localized string returned by a message catalog's get() method, that contains %n% placeholders. The remaining variadic arguments to gettextmsg() provide the values for each placeholder. Each placeholder gets replaced by the nth variadic parameter. The message catalog may specify a string with placeholders appearing in a different order, the parameters get rearranged accordingly. gettextmsg returns an object that can be used with the << for an output stream, or assigned directly to a string.

The argument to gettextmsg() may be a narrow or a wide character string. The result of gettextmsg() can be used used with the <<, or assigned to a narrow or a wide stream/string, appropriately.

Each formatting parameter may be any class with a copy constructor and a << operator into an output stream. This includes I/O manipulators, which are treated no differently than any other parameter. The << operator may write large amounts of output into an output stream. gettextmsg uses the << operator to process the formatting string and its parameters, in the specified order. The parameters will write their output directly into an output stream, or into a temporary string stream if the result of gettextmsg gets assigned to a string; but when the output goes to an output stream directly, no temporary buffer is needed, so large output from a class's << operator does not get buffered, and goes directly to the output stream.

For convenience, message catalogs provide a format() method, that employs gettextmsg():

std::string str=msgcat->format("Window size: %1% rows, %2% columns",
                      nrows, ncols);

Single and plural forms

#include <x/messages.H>

void onthewall(size_t nbeers)
{
    x::messages msgcat(x::messages::create(l, "app"));

    printf(msgcat->get("%d bottle of beer\n",
                       "%d bottles of beer\n", nbeers).c_str(),
        nbeers);
}

A three-argument form of get() implements localization of single and plural forms of a given string. Different locales may use something other than a 1 is singular, all other values are plural rule. This form of get() returns a localized string that corresponds to the numerical value of the third parameter.

formatn() combines this with gettextmsg:

#include <x/messages.H>

void onthewall(size_t nbeers)
{
    x::messages msgcat(x::messages::create(l, "app"));

    std::cout << msgcat->formatn("%1% bottle of beer",
                                 "%1% bottles of beer", nbeers,
                                 nbeers) << std::endl;
}

This is equivalent to calling the three argument version of get() and then using gettextmsg(). Note that nbeers appears twice, in the above example. Its first occurence becomes a parameter to get() that selects the singular or the plural form of a localized string. The second occurence becomes the first formatting parameter, that replaces the %1% placeholder.