docs/doxygen/overviews/nonenglish.h

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