docs/doxygen/overviews/nonenglish.h

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