docs/doxygen/overviews/internationalization.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        internationalization.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9
  10 @page overview_i18n Internationalization
  11
  12 @tableofcontents
  13
  14 Although internationalization of an application (i18n for short) involves far
  15 more than just translating its text messages to another message - date, time
  16 and currency formats need changing too, some languages are written left to
  17 right and others right to left, character encoding may differ and many other
  18 things may need changing too - it is a necessary first step. wxWidgets provides
  19 facilities for message translation with its wxLocale class and is itself fully
  20 translated into several languages. Please consult wxWidgets home page for the
  21 most up-to-date translations - and if you translate it into one of the
  22 languages not done yet, your translations would be gratefully accepted for
  23 inclusion into future versions of the library!
  24
  25 The wxWidgets approach to i18n closely follows the GNU gettext package.
  26 wxWidgets uses the message catalogs which are binary compatible with gettext
  27 catalogs and this allows to use all of the programs in this package to work
  28 with them. But note that no additional libraries are needed during run-time,
  29 however, so you have only the message catalogs to distribute and nothing else.
  30
  31 During program development you will need the gettext package for working with
  32 message catalogs. @b Warning: gettext versions @< 0.10 are known to be buggy,
  33 so you should find a later version of it!
  34
  35 There are two kinds of message catalogs: source catalogs which are text files
  36 with extension .po and binary catalogs which are created from the source ones
  37 with @e msgfmt program (part of gettext package) and have the extension .mo.
  38 Only the binary files are needed during program execution.
  39
  40 Translating your application involves several steps:
  41
  42 @li Translating the strings in the program text using wxGetTranslation or
  43     equivalently the @c _() macro.
  44 @li Extracting the strings to be translated from the program: this uses the
  45     work done in the previous step because @c xgettext program used for string
  46     extraction recognises the standard @c _() as well as (using its @c -k
  47     option) our wxGetTranslation and extracts all strings inside the calls to
  48     these functions. Alternatively, you may use @c -a option to extract all the
  49     strings, but it will usually result in many strings being found which don't
  50     have to be translated at all. This will create a text message catalog - a
  51     .po file.
  52 @li Translating the strings extracted in the previous step to other
  53     language(s). It involves editing the .po file.
  54 @li Compiling the .po file into .mo file to be used by the program.
  55 @li Installing the .mo files with your application in the appropriate location
  56     for the target system (@see overview_i18n_mofiles).
  57 @li Setting the appropriate locale in your program to use the strings for the
  58     given language: see wxLocale.
  59
  60
  61 @section overview_i18n_mofiles Installing translation catalogs
  62
  63 The .mo files with compiled catalogs must be included with the application.
  64 By default, wxFileTranslationsLoader is used to load them from files installed
  65 alongside the application (although you could use wxResourceTranslationsLoader
  66 or some custom loader too).
  67
  68 The files are expected to be in the resources directory (as returned by
  69 wxStandardPaths::GetLocalizedResourcesDir(wxStandardPaths::ResourceCat_Messages).
  70 If the message catalogs are not installed in this default location you may
  71 explicitly use wxFileTranslationsLoader::AddCatalogLookupPathPrefix() to still
  72 allow wxWidgets to find them, but it is recommended to use the default
  73 locations when possible.
  74
  75 Depending on the platform, the default location differs. On Windows, it is
  76 alongside the executable. On Unix, translations are expected to be in
  77 "$prefix/share/locale". On OS X, application bundle's @em Resources subdirectory
  78 is used.
  79
  80 In all cases, translations are searched for in subdirectories named using the
  81 languages codes from ISO 639. The .mo file(s) should be located either directly
  82 in that directory or in LC_MESSAGES subdirectory. On OS X, ".lproj" extension
  83 is used for the per-languages Resources subdirectories.
  84
  85 Here's how an app would typically install the files on Unix:
  86 @code
  87 /usr/bin/myapp
  88 /usr/share/locale/de/LC_MESSAGES/myapp.mo
  89 /usr/share/locale/fr/LC_MESSAGES/myapp.mo
  90 @endcode
  91 And on OS X:
  92 @code
  93 MyApp.app/Contents/MacOS/MyApp
  94 MyApp.app/Contents/Resources/de.lproj/myapp.mo
  95 MyApp.app/Contents/Resources/fr.lproj/myapp.mo
  96 @endcode
  97 And on Windows:
  98 @code
  99 C:\Program Files\MyApp\myapp.exe
 100 C:\Program Files\MyApp\de\myapp.mo
 101 C:\Program Files\MyApp\fr\myapp.mo
 102 @endcode
 103 It is of course possible to use the Unix layout everywhere instead.
 104
 105
 106 @section overview_i18n_menuaccel Translating Menu Accelerators
 107
 108 If you translate the accelerator modifier names (Ctrl, Alt and Shift) in your
 109 menu labels, you may find the accelerators no longer work. In your message
 110 catalogs, you need to provide individual translations of these modifiers from
 111 their lower case names (ctrl, alt, shift) so that the wxWidgets accelerator
 112 code can recognise them even when translated. wxWidgets does not provide
 113 translations for all of these currently. wxWidgets does not yet handle
 114 translated special key names such as Backspace, End, Insert, etc.
 115
 116
 117 @see
 118 @li The gettext Manual: http://www.gnu.org/software/gettext/manual/gettext.html
 119 @li @ref overview_nonenglish - It focuses on handling charsets related problems.
 120 @li @ref page_samples_internat - Shows you how all this looks in practice.
 121
 122 */