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