docs/doxygen/overviews/internationalization.h

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