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