Providing Translations

wxWidgets provides facilities for message translation using the wxLocale class and is itself fully translated into several languages. Please consult the wxWidgets home page for the most up-to-date translations.

The wxWidgets approach to internationalization closely follows the GNU gettext package. wxWidgets uses message catalogs, which are binary compatible with gettext catalogs allowing you to use all the gettext tools. No additional libraries are needed during runtime because wxWidgets is able to read message catalogs.

During program development, you will need the gettext package for working with message catalogs (or poEdit; see the next section). There are two kinds of message catalog: source catalogs, which are text files with extension .po, and binary catalog which are created from the source files with the msgfmt program (part of the gettext package) and have the extension .mo. Only the binary files are needed during program execution. For each language you support, you need one message catalog.

poEdit

You don't have to use command-line tools for maintaining your message catalogs. Vaclav Slavik has written poEdit, a graphical front-end to the gettext package available from http://www.poedit.org. poEdit, shown in Figure 16-1, helps you to maintain message catalogs, generate .mo files, and merge in changes to strings in your application code as your application changes and grows.

Figure 16-1. poEdit

Step-by-Step Guide to Using Message Catalogs

These are the steps you need to follow to create and use message catalogs:

1.	Wrap literal strings in the program text that should be translated with wxGettranslation or equivalently with the _() macro. Strings that will not be translated should be wrapped in wxT() or the alias _T() to make them Unicode-compatible.
2.	Extract the strings to be translated from the program into a .po file. Fortunately, you don't have to do this by hand; you can use the xgettext program or, more easily, poEdit. If you use xgettext, you can use the -k option to recognize wxGettranslation as well as _(). poEdit can also be configured to recognize wxGettranslation via the catalog settings dialog.
3.	Translate the strings extracted in the previous step to another language by editing the .po file or using poEdit (one .po file per language). You must also indicate the character set you are using for the translated strings. If you do not use poEdit, you will have to do it by hand, using your favorite text editor. The header of your .po file will look something this: # SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR Free Software Foundation, Inc. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "POT-Creation-Date: 1999-02-19 16:03+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <[e-mail]>\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=iso8859-1\n" "Content-Transfer-Encoding: 8bit\n" Note the charset property in the second to last line, specifying the character set used by the catalog. All strings in the catalog are encoded using this character set. This is very important if non-Unicode encodings are used because otherwise the GUI elements cannot correctly display all characters.
4.	Compile the .po file into the binary .mo file to be used by the program. You can do this within poEdit, or you might want to add it as a step in your distribution script, for example using: msgfmt -o myapp.mo myapp.po
5.	Set the appropriate locale in your program to use the strings for the given language (see the next section, "Using wxLocale").

Under Mac OS X, you'll need to make one modification to the Info.plist file, which describes the contents of the "application bundle." This file (an XML text file encoded in UTF-8) should have a CFBundleDevelopmentRegion entry describing the language of the developersuch as Englishand Mac OS X will query the bundle for the presence of certain resource directories to find out which languages are supported. For example, for German, this might be the directory German.lproj. Because wxWidgets applications do not use these directories for storing resource information, instead storing the translation in .mo files, the application needs to be told explicitly which languages are supported. You do this by adding a CFBundleLocalizations entry to Info.plist. It might look like this:

 <key>CFBundleDevelopmentRegion</key> <string>English</string> <key>CFBundleLocalizations</key> <array>        <string>en</string>        <string>de</string>        <string>fr</string> </array> 

Using wxLocale

The wxLocale class encapsulates all language-dependent settings and is a generalization of the C locale concept. Normally you add a wxLocale member variable to your application class, say m_locale, and in your application OnInit function, you initialize the locale as follows:

 if (m_locale.Init(wxLANGUAGE_DEFAULT,                     wxLOCALE_LOAD_DEFAULT | wxLOCALE_CONV_ENCODING)) {     m_locale.AddCatalog(wxT("myapp")); } 

Note that wxLocale::Init will try to find and add the wxstd.mo catalog, containing wxWidgets' own translations. The parameter wxLANGUAGE_DEFAULT means use the system language, and you can also force a certain language using the correct wxLANGUAGE_xxx code.

When you tell the wxLocale class to load a message catalog, the catalog is converted to the character set used by the user's operating system. This is the default behavior of the wxLocale class; you can disable it by not passing wxLOCALE_CONV_ENCODING to wxLocale::Init as the second parameter.

Where does wxWidgets find its message catalogs? For each directory <DIR> in its internal list, wxWidgets looks in:

• <DIR>/<LANG>/LC_MESSAGES

• <DIR>/<LANG>

• <DIR>

The rules about which directories are taken into account are different on each platform:

• On all platforms, the value of the LC_PATH environment variable is searched.

• On Unix and Mac OS X, the wxWidgets installation directory is searched, and also /share/locale, /usr/share/locale, /usr/lib/locale, /usr/locale /share/locale, and the current directory.

• On Windows, the application directory is also searched.

You can add further search directories using the function wxLocale:: AddCatalogLookupPathPrefix. For example:

 wxString resDir = GetAppDir() + wxFILE_SEP_PATH + wxT("resources"); m_locale.AddCatalogLookupPathPrefix(resDir); // If resDir is c:\MyApp\resources, AddCatalog will now look for the // French catalog in these places as well as the standard dirs: // // c:\MyApp\resources\fr\LC_MESSAGES\myapp.mo // c:\MyApp\resources\fr\myapp.mo // c:\MyApp\resources\myapp.mo m_locale.AddCatalog(wxT("myapp")); 

The usual method for distributing message catalogs is to create a subdirectory for each language, using the standard canonical name, containing <appname>.mo in each directory. For example, the wxWidgets internat sample has directories fr and de representing French and German using ISO 639 language codes.