added a note that wxStringList is obsolete

[wxWidgets.git] / docs / latex / wx / tnoneng.tex

\section{Writing non-English applications}\label{nonenglishoverview}

This article describes how to write applications that communicate with
user in language other than English. Unfortunately many languages use
different charsets under Unix and Windows (and other platforms, to make
situation even more complicated). These charsets usually differ in so
many characters it is impossible to use same texts under all platforms.

wxWindows library provides mechanism that helps you avoid distributing many
identical, only differently encoded, packages with your application 
(e.g. help files and menu items in iso8859-13 and windows-1257). Thanks
to this mechanism you can, for example, distribute only iso8859-13 data 
and it will be handled transparently under all systems.

Please read \helpref{Internationalization}{internationalization} which
describes the locales concept.

In the following text, wherever {\it iso8859-2} and {\it windows-1250} are
used, any encodings are meant and any encodings may be substituted there.

\wxheading{Locales}

The best way to ensure correctly displayed texts in a GUI across platforms
is to use locales. Write your in-code messages in English or without 
diacritics and put real messages into the message catalog (see 
\helpref{Internationalization}{internationalization}).

A standard .po file begins with a header like this:

\begin{verbatim}
# 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 <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=CHARSET\n"
"Content-Transfer-Encoding: ENCODING\n"
\end{verbatim}

Notice this particular line:

\begin{verbatim}
"Content-Type: text/plain; charset=CHARSET\n"
\end{verbatim}

It specifies the charset used by the catalog. All strings in the catalog
are encoded using this charset.

You have to fill in proper charset information. Your .po file may look like this
after doing so: 

\begin{verbatim}
# 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 <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=iso8859-2\n"
"Content-Transfer-Encoding: 8bit\n"
\end{verbatim}

(Make sure that the header is {\bf not} marked as {\it fuzzy}.)

wxWindows is able to use this catalog under any supported platform
(although iso8859-2 is a Unix encoding and is normally not understood by
Windows).

How is this done? When you tell the wxLocale class to load a message catalog that
contains correct header, it checks the charset. If the
charset is "alien" on the platform the program is currently running (e.g.
any of ISO encodings under Windows or CP12XX under Unix) it uses 
\helpref{wxEncodingConverter::GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents}
to obtain an encoding that is more common on this platform and converts
the message catalog to this encoding. Note that it does {\bf not} check
for presence of fonts in the "platform" encoding! It only assumes that it is
always better to have strings in platform native encoding than in an encoding
that is rarely (if ever) used.

The behaviour described above is disabled by default.
You must set {\it bConvertEncoding} to TRUE in 
\helpref{wxLocale constructor}{wxlocaledefctor} in order to enable
runtime encoding conversion.

\wxheading{Font mapping}

You can use \helpref{wxEncodingConverter}{wxencodingconverter} and 
\helpref{wxFontMapper}{wxfontmapper} to display text:

\begin{verbatim}
if (!wxTheFontMapper->IsEncodingAvailable(enc, facename))
{
   wxFontEncoding alternative;
   if (wxTheFontMapper->GetAltForEncoding(enc, &alternative, 
                                          facename, FALSE))
   {
       wxEncodingConverted encconv;
       if (!encconv.Init(enc, alternative))
           ...failure...
       else
           text = encconv.Convert(text);
   }
   else
       ...failure...
}
...display text...
\end{verbatim}

\wxheading{Converting data}

You may want to store all program data (created documents etc.) in
the same encoding, let's say windows1250. Obviously, the best way would
be to use \helpref{wxEncodingConverter}{wxencodingconverter}.

\wxheading{Help files}

If you're using \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} there is
no problem at all. You must only make sure that all the HTML files contain
the META tag, e.g.

\begin{verbatim}
<meta http-equiv="Content-Type" content="text/html; charset=iso8859-2">
\end{verbatim}

and that the hhp project file contains one additional line in the {\tt OPTIONS}
section:

\begin{verbatim}
Charset=iso8859-2
\end{verbatim}

This additional entry tells the HTML help controller what encoding is used
in contents and index tables.