docs/doxygen/overviews/internationalization.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        internationalization
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page internationalization_overview Internationalization
  12
  13  Although internationalization of an application (i18n for short) involves far
  14  more than just translating its text messages to another message - date, time and
  15  currency formats need changing too, some languages are written left to right
  16  and others right to left, character encoding may differ and many other things
  17  may need changing too - it is a necessary first step. wxWidgets provides
  18  facilities for message translation with its
  19  #wxLocale class and is itself fully translated into several
  20  languages. Please consult wxWidgets home page for the most up-to-date
  21  translations - and if you translate it into one of the languages not done
  22  yet, your translations would be gratefully accepted for inclusion into future
  23  versions of the library!
  24  The wxWidgets approach to i18n closely follows the GNU gettext package. wxWidgets uses the
  25  message catalogs which are binary compatible with gettext catalogs and this
  26  allows to use all of the programs in this package to work with them. But note
  27  that no additional libraries are needed during run-time, however, so you
  28  have only the message catalogs to distribute and nothing else.
  29  During program development you will need the gettext package for
  30  working with message catalogs. @b Warning: gettext versions  0.10 are known
  31  to be buggy, so you should find a later version of it!
  32  There are two kinds of message catalogs: source catalogs which are text files
  33  with extension .po and binary catalogs which are created from the source ones
  34  with @e msgfmt program (part of gettext package) and have the extension .mo.
  35  Only the binary files are needed during program execution.
  36  The program i18n involves several steps:
  37
  38
  39   Translating the strings in the program text using
  40  #wxGetTranslation or equivalently the
  41  #_() macro.
  42   Extracting the strings to be translated from the program: this uses the
  43  work done in the previous step because @c xgettext program used for string
  44  extraction recognises the standard _() as well as (using its @c -k option)
  45  our wxGetTranslation and extracts all strings inside the calls to these
  46  functions. Alternatively, you may use @c -a option to extract all the
  47  strings, but it will usually result in many strings being found which don't
  48  have to be translated at all. This will create a text message catalog - a .po
  49  file.
  50   Translating the strings extracted in the previous step to other
  51  language(s). It involves editing the .po file.
  52   Compiling the .po file into .mo file to be used by the program.
  53   Installing the .mo files with your application in the appropriate
  54  location for the target system which is the one returned by
  55  wxStandardPaths::GetLocalizedResourcesDir(wxStandardPaths::ResourceCat_Messages).
  56  If the message catalogs are not installed in this default location you may
  57  explicitly use #AddCatalogLookupPathPrefix() to
  58  still allow wxWidgets to find them but it is strongly recommended to use the
  59  default directory.
  60   Setting the appropriate locale in your program to use the strings for the
  61  given language: see #wxLocale.
  62
  63
  64  See also the http://www.gnu.org/software/gettext/manual/gettext.html.
  65  See also @ref nonenglish_overview.
  66  It focuses on handling charsets related problems.
  67  Finally, take a look at the @ref sampleinternat_overview which shows
  68  you how all this looks in practice.
  69  @b Translating menu accelerators
  70  If you translate the accelerator modifier names (Ctrl, Alt and Shift) in your menu labels, you may find
  71  the accelerators no longer work. In your message catalogs, you need to provide individual translations
  72  of these modifiers from their lower case names (ctrl, alt, shift) so that the wxWidgets accelerator
  73  code can recognise them even when translated. wxWidgets does not provide translations for all of these
  74  currently. wxWidgets does not yet handle translated special key names such as Backspace,
  75  End, Insert, etc.
  76
  77  */
  78
  79