Wt: Wt::WMessageResourceBundle Class Reference

Wt 4.10.4

Loading...
Searching...
No Matches
Public Member Functions | List of all members
Wt::WMessageResourceBundle Class Reference

Support for localized strings using XML files. More...

`#include <Wt/WMessageResourceBundle.h>`

Inheritance diagram for Wt::WMessageResourceBundle:
[legend]

## Public Member Functions
| WMessageResourceBundle ()
| Creates a message resource bundle.
void | use (const std::string &path, bool loadInMemory=true)
| Adds a (series) of message resource files to be used.
const std::set< std::string > | keys (const WLocale &locale) const
| Returns a set of all keys in this bundle.
virtual void | hibernate () override
| Purges memory resources, if possible.
virtual LocalizedString | resolveKey (const WLocale &locale, const std::string &key) override
| Resolves a key in the given locale.
virtual LocalizedString | resolvePluralKey (const WLocale &locale, const std::string &key, ::uint64_t amount) override
| Resolves the plural form of a key in the given locale.
Public Member Functions inherited from Wt::WLocalizedStrings
virtual | ~WLocalizedStrings ()
| Destructor.

## Additional Inherited Members
Static Public Member Functions inherited from Wt::WLocalizedStrings
static int | evaluatePluralExpression (const std::string &expression, ::uint64_t n)
| Utility method to evaluate a plural expression.

## Detailed Description

Support for localized strings using XML files.

The resource bundle manages a number of resource files, which allow the developer to conceptually manage its messages in a number of libraries.

For example, a WApplication may have a generic message library, that is shared with many other libraries, with re-occurring messages (such as 'welcome', 'add to shopping cart', and 'pay'), and a specific message library for specific messages.

Usage example:

XML file "general.xml":

     <?xml version="1.0" encoding="UTF-8"?>
     <messages>

       <message id='welcome-text'>
         Welcome dear visiter, {1} of the WFooBar magic website !
       </message>

       <message id='company-policy'>
         The company policy is to <b>please our share-holders</b>.
       </message>

     </messages>

The encodings supported are ASCII, UTF-8 (recommended) or UTF-16.

Use this resource bundle in your program:

// load the message resource bundle
Wt::WApplication *app = Wt::WApplication::instance();
app->messageResourceBundle().use("general");
// resolve a string using the resource bundle
auto welcome = std::make_unique<Wt::WText>(
tr("welcome-text").arg("Bart"));
Wt::WApplication
Represents an application instance for a single session.
Definition WApplication.h:211
Wt::WApplication::messageResourceBundle
WMessageResourceBundle & messageResourceBundle()
Returns the message resource bundle.
Wt::WApplication::instance
static WApplication * instance()
Returns the current application instance.
Wt::WMessageResourceBundle::use
void use(const std::string &path, bool loadInMemory=true)
Adds a (series) of message resource files to be used.

To refer the two messages defined in this resource file, use WString::tr("welcome-text").arg(userName) or WWidget::tr("company-policy").

### Plural forms

The XML format supports plural noun forms, and allows the definition of different cases of plural nouns, per language. The amount of cases per noun may differ between language families, as does the expression to transform a number associated with a noun into a case id. Two attributes for the `messages` XML element configure the plural support:

- the 'nplurals' attribute indicates the number of plural cases; cases are numbered 0 .. (nplurals - 1).
- the 'plural' attribute is an expression which evaluates converts a count n into a plural case. This expression should use the C language syntax, with the exception that no negative numbers are allowed, numbers must be integers, and the only allowed variable is n, which corresponds to the amount passed to WString::trn(). The resulting value must be a plural case: 0 .. (nplurals - 1).

Using WString::trn(), you can pass the count n that is used to select a suitable plural case.

As an example, consider an XML resource file describing Polish translations, which enlists all plural cases of the noun 'plik' (file in Polish). The noun is used this way:

- 1 plik
- 2,3,4 pliki
- 5-21 pliko'w
- 22-24 pliki
- 25-31 pliko'w

    <?xml version="1.0" encoding="UTF-8"?>
      <messages nplurals="3"
                plural="n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2">

        <message id="file">
          <plural case="0">{1} plik</plural>
          <plural case="1">{1} pliki</plural>
          <plural case="2">{1} pliko'w</plural>
        </message>

      </messages>

To message defined in this resource file can then be used using WString::trn("file", n).

See also
  WApplication::locale(), WString::tr(), WString::trn()

## Member Function Documentation

## ◆ hibernate()

virtual void Wt::WMessageResourceBundle::hibernate | ( |  | ) |
| overridevirtual

Purges memory resources, if possible.

This is called afer event handling, and is an opportunity to conserve memory inbetween events, by freeing memory used for cached key/value bindings, if applicable.

The default implementation does nothing.

Reimplemented from Wt::WLocalizedStrings.

## ◆ keys()

const std::set< std::string > Wt::WMessageResourceBundle::keys | ( | const WLocale & | locale | ) | const

Returns a set of all keys in this bundle.

Returns a set of all keys connected with this WMessageResources, within the scope provided as parameter.

## ◆ resolveKey()

virtual LocalizedString Wt::WMessageResourceBundle::resolveKey | ( | const WLocale & | locale,
|  | const std::string & | key )
| overridevirtual

Resolves a key in the given locale.

This method is used by WString to obtain the UTF-8 value corresponding to a key in the given locale.

Returns a successful LocalizedString if the key could be resolved.

See also
  WString::tr()

Implements Wt::WLocalizedStrings.

## ◆ resolvePluralKey()

virtual LocalizedString Wt::WMessageResourceBundle::resolvePluralKey | ( | const WLocale & | locale,
|  | const std::string & | key,
|  | ::uint64_t | amount )
| overridevirtual

Resolves the plural form of a key in the given locale.

This method is used by WString to obtain the UTF-8 value corresponding to a key in the current locale, taking into account the possibility of multiple plural forms, and chosing the right plural form based on the `amount` passed.

Throws a std::logic_error if the underlying implementation does not provide support for plural internationalized strings.

Returns a successful LocalizedString if the key could be resolved.

See also
  WString::trn()

Reimplemented from Wt::WLocalizedStrings.

## ◆ use()

void Wt::WMessageResourceBundle::use | ( | const std::string & | path,
|  | bool | loadInMemory = true )

Adds a (series) of message resource files to be used.

The `path` is not a URI, and relative paths will be resolved with respect to the working directory of the server. The XML files do not need to be deployed in the web server's docroot.

When you give as `path:` /path/to/name, then the following message resource files will be used:

- /path/to/name.xml (default, English)
- /path/to/name_nl.xml (for Dutch)
- /path/to/name_fr.xml (for French)
- etc...

The message file that is used depends on the application's locale.

See also
  WApplication::locale()