\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
+the user in a 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 provide mechanism that helps you avoid distributing many
+the situation even more complicated). These charsets usually differ in so
+many characters that it is impossible to use the same texts under all
+platforms.
+
+The wxWidgets library provides a 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 distribute only let's say iso8859-13 data
+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 locales concept.
+describes the locales concept.
-Whereever in the following text {\it iso8859-2} and {\it windows-1250} are
+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 how to ensure correctly displayed texts in GUI across platforms
+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 message catalog (see
+diacritics and put real messages into the message catalog (see
\helpref{Internationalization}{internationalization}).
-Standard .po file begins with a header like this:
+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.
#
-#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Content-Transfer-Encoding: ENCODING\n"
\end{verbatim}
-Notice these two lines:
+Note this particular line:
\begin{verbatim}
-#, fuzzy
"Content-Type: text/plain; charset=CHARSET\n"
\end{verbatim}
-The first tells {\it msgfmt} compiler not to include string "" (empty)
-to compiled .mo catalog. Second one informs about charset used to write
-translated messages.
+It specifies the charset used by the catalog. All strings in the catalog
+are encoded using this charset.
-You have to do 2 things: fill-in proper charset information and delete
-the {\tt fuzzy} line. Your .po file may look like this after doing so:
+You have to fill in proper charset information. Your .po file may look like this
+after doing so:
\begin{verbatim}
# SOME DESCRIPTIVE TITLE.
"Language-Team: LANGUAGE <LL@li.org>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=iso8859-2\n"
-"Content-Transfer-Encoding: ENCODING\n"
+"Content-Transfer-Encoding: 8bit\n"
\end{verbatim}
-wxWindows is able to use this catalog under any supported platform
-(although iso8859-2 is Unix encoding and is not understood by Windows).
-
-How is this done? When you tell wxLocale class to load message catalog that
-contains the header (msgid "". Normal .mo catalogs do {\bf not} contain it,
-you must remove the line with {\it fuzzy}!), 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 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 this 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 about is disabled by default.
-You must set {\it bConvertEncoding} to TRUE in
-\helpref{wxLocale constructor}{wxlocaledefctor} in order to enable
-runtime encoding conversion!
+(Make sure that the header is {\bf not} marked as {\it fuzzy}.)
+
+wxWidgets 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 a correct header, it checks the charset. The catalog is then converted
+to the charset used (see
+\helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding} and
+\helpref{wxLocale::GetSystemEncodingName}{wxlocalegetsystemencodingname}) by
+the user's operating system. This is the default behaviour of the
+\helpref{wxLocale}{wxlocale} class; you can disable it by {\bf not} passing
+{\tt wxLOCALE\_CONV\_ENCODING} to \helpref{wxLocale::Init}{wxlocaleinit}.
+
+\wxheading{Non-English strings or 8-bit characters in the source code}
+
+By convention, you should only use characters without diacritics (i.e. 7-bit
+ASCII strings) for msgids in the source code and write them in English.
+
+If you port software to wxWindows, you may be confronted with legacy source
+code containing non-English string literals. Instead of translating the strings
+in the source code to English and putting the original strings into message
+catalog, you may configure wxWidgets to use non-English msgids and translate to
+English using message catalogs:
+
+\begin{enumerate}
+\item{If you use the program {\tt xgettext} to extract the strings from
+the source code, specify the option {\tt --from-code=<source code charset>}.}
+\item{Specify the source code language and charset as arguments to
+\helpref{wxLocale::AddCatalog}{wxlocaleaddcatalog}. For example:
+\begin{verbatim}
+locale.AddCatalog(_T("myapp"),
+ wxLANGUAGE_GERMAN, _T("iso-8859-1"));
+\end{verbatim}
+}
+\end{enumerate}
\wxheading{Font mapping}
-You can use \helpref{wxEncodingConverter}{wxencodingconverter} and
+You can use \helpref{wxMBConv classes}{mbconvclasses} and
\helpref{wxFontMapper}{wxfontmapper} to display text:
\begin{verbatim}
-if (!wxTheFontMapper->IsEncodingAvailable(enc, facename))
+if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
{
wxFontEncoding alternative;
- if (wxTheFontMapper->GetAltForEncoding(enc, &alternative,
- facename, FALSE))
+ if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
+ facename, false))
{
- wxEncodingConverted encconv;
- if (!encconv.Init(enc, alternative))
- ...failure...
- else
- text = encconv.Convert(text);
+ wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
+ wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
+ text = wxString(text.mb_str(convFrom), convTo);
}
else
- ...failure...
+ ...failure (or we may try iso8859-1/7bit ASCII)...
}
...display text...
\end{verbatim}
\wxheading{Converting data}
You may want to store all program data (created documents etc.) in
-same encoding, let's say windows1250. Obviously, the best way would
-be to use \helpref{wxEncodingConverter}{wxencodingconverter}.
+the same encoding, let's say {\tt utf-8}. You can use
+\helpref{wxCSConv}{wxcsconv} class to convert data to the encoding used by the
+system your application is running on (see
+\helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding}).
\wxheading{Help files}
If you're using \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} there is
-no problem at all. You must only make sure that all HTML files contain
-META tag, e.g.
+no problem at all. You only need to make sure that all the HTML files contain
+the META tag, e.g.
\begin{verbatim}
-<meta http-equiv="Content-Type" content="iso8859-2">
+<meta http-equiv="Content-Type" content="text/html; charset=iso8859-2">
\end{verbatim}
-and that hhp project file contains one additional line in {\tt OPTIONS}
+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 HTML help controller what encoding is used
+This additional entry tells the HTML help controller what encoding is used
in contents and index tables.
projects / wxWidgets.git / blobdiff