docs/latex/wx/tnoneng.tex

   1 \section{Writing non-English applications}\label{nonenglishoverview}
   2
   3 This article describes how to write applications that communicate with
   4 the user in a language other than English. Unfortunately many languages use
   5 different charsets under Unix and Windows (and other platforms, to make
   6 the situation even more complicated). These charsets usually differ in so
   7 many characters that it is impossible to use the same texts under all
   8 platforms.
   9
  10 The wxWidgets library provides a mechanism that helps you avoid distributing many
  11 identical, only differently encoded, packages with your application
  12 (e.g. help files and menu items in iso8859-13 and windows-1257). Thanks
  13 to this mechanism you can, for example, distribute only iso8859-13 data
  14 and it will be handled transparently under all systems.
  15
  16 Please read \helpref{Internationalization}{internationalization} which
  17 describes the locales concept.
  18
  19 In the following text, wherever {\it iso8859-2} and {\it windows-1250} are
  20 used, any encodings are meant and any encodings may be substituted there.
  21
  22 \wxheading{Locales}
  23
  24 The best way to ensure correctly displayed texts in a GUI across platforms
  25 is to use locales. Write your in-code messages in English or without
  26 diacritics and put real messages into the message catalog (see
  27 \helpref{Internationalization}{internationalization}).
  28
  29 A standard .po file begins with a header like this:
  30
  31 \begin{verbatim}
  32 # SOME DESCRIPTIVE TITLE.
  33 # Copyright (C) YEAR Free Software Foundation, Inc.
  34 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
  35 #
  36 msgid ""
  37 msgstr ""
  38 "Project-Id-Version: PACKAGE VERSION\n"
  39 "POT-Creation-Date: 1999-02-19 16:03+0100\n"
  40 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
  41 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
  42 "Language-Team: LANGUAGE <LL@li.org>\n"
  43 "MIME-Version: 1.0\n"
  44 "Content-Type: text/plain; charset=CHARSET\n"
  45 "Content-Transfer-Encoding: ENCODING\n"
  46 \end{verbatim}
  47
  48 Note this particular line:
  49
  50 \begin{verbatim}
  51 "Content-Type: text/plain; charset=CHARSET\n"
  52 \end{verbatim}
  53
  54 It specifies the charset used by the catalog. All strings in the catalog
  55 are encoded using this charset.
  56
  57 You have to fill in proper charset information. Your .po file may look like this
  58 after doing so:
  59
  60 \begin{verbatim}
  61 # SOME DESCRIPTIVE TITLE.
  62 # Copyright (C) YEAR Free Software Foundation, Inc.
  63 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
  64 #
  65 msgid ""
  66 msgstr ""
  67 "Project-Id-Version: PACKAGE VERSION\n"
  68 "POT-Creation-Date: 1999-02-19 16:03+0100\n"
  69 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
  70 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
  71 "Language-Team: LANGUAGE <LL@li.org>\n"
  72 "MIME-Version: 1.0\n"
  73 "Content-Type: text/plain; charset=iso8859-2\n"
  74 "Content-Transfer-Encoding: 8bit\n"
  75 \end{verbatim}
  76
  77 (Make sure that the header is {\bf not} marked as {\it fuzzy}.)
  78
  79 wxWidgets is able to use this catalog under any supported platform
  80 (although iso8859-2 is a Unix encoding and is normally not understood by
  81 Windows).
  82
  83 How is this done? When you tell the wxLocale class to load a message catalog that
  84 contains a correct header, it checks the charset. The catalog is then converted
  85 to the charset used (see
  86 \helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding} and
  87 \helpref{wxLocale::GetSystemEncodingName}{wxlocalegetsystemencodingname}) by
  88 the user's operating system. This is the default behaviour of the
  89 \helpref{wxLocale}{wxlocale} class; you can disable it by {\bf not} passing
  90 {\tt wxLOCALE\_CONV\_ENCODING} to \helpref{wxLocale::Init}{wxlocaleinit}.
  91
  92 \wxheading{Non-English strings or 8-bit characters in the source code}
  93
  94 By convention, you should only use characters without diacritics (i.e. 7-bit
  95 ASCII strings) for msgids in the source code and write them in English.
  96
  97 If you port software to wxWindows, you may be confronted with legacy source
  98 code containing non-English string literals. Instead of translating the strings
  99 in the source code to English and putting the original strings into message
 100 catalog, you may configure wxWidgets to use non-English msgids and translate to
 101 English using message catalogs:
 102
 103 \begin{enumerate}
 104 \item{If you use the program {\tt xgettext} to extract the strings from
 105 the source code, specify the option {\tt --from-code=<source code charset>}.}
 106 \item{Specify the source code language and charset as arguments to
 107 \helpref{wxLocale::AddCatalog}{wxlocaleaddcatalog}. For example:
 108 \begin{verbatim}
 109 locale.AddCatalog(_T("myapp"),
 110                   wxLANGUAGE_GERMAN, _T("iso-8859-1"));
 111 \end{verbatim}
 112 }
 113 \end{enumerate}
 114
 115 \wxheading{Font mapping}
 116
 117 You can use \helpref{wxMBConv classes}{mbconvclasses} and
 118 \helpref{wxFontMapper}{wxfontmapper} to display text:
 119
 120 \begin{verbatim}
 121 if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
 122 {
 123    wxFontEncoding alternative;
 124    if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
 125                                               facename, false))
 126    {
 127        wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
 128        wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
 129        text = wxString(text.mb_str(convFrom), convTo);
 130    }
 131    else
 132        ...failure (or we may try iso8859-1/7bit ASCII)...
 133 }
 134 ...display text...
 135 \end{verbatim}
 136
 137 \wxheading{Converting data}
 138
 139 You may want to store all program data (created documents etc.) in
 140 the same encoding, let's say {\tt utf-8}. You can use
 141 \helpref{wxCSConv}{wxcsconv} class to convert data to the encoding used by the
 142 system your application is running on (see
 143 \helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding}).
 144
 145 \wxheading{Help files}
 146
 147 If you're using \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} there is
 148 no problem at all. You only need to make sure that all the HTML files contain
 149 the META tag, e.g.
 150
 151 \begin{verbatim}
 152 <meta http-equiv="Content-Type" content="text/html; charset=iso8859-2">
 153 \end{verbatim}
 154
 155 and that the hhp project file contains one additional line in the {\tt OPTIONS}
 156 section:
 157
 158 \begin{verbatim}
 159 Charset=iso8859-2
 160 \end{verbatim}
 161
 162 This additional entry tells the HTML help controller what encoding is used
 163 in contents and index tables.
 164