docs/latex/wx/ti18n.tex

   1 \section{Internationalization}\label{internationalization}
   2
   3 Although internationalization of an application (i18n for short) involves far
   4 more than just translating its text messages to another message -- date, time and
   5 currency formats need changing too, some languages are written left to right
   6 and others right to left, character encoding may differ and many other things
   7 may need changing too -- it is a necessary first step. wxWidgets provides
   8 facilities for message translation with its
   9 \helpref{wxLocale}{wxlocale} class and is itself fully translated into several
  10 languages. Please consult wxWidgets home page for the most up-to-date
  11 translations - and if you translate it into one of the languages not done
  12 yet, your translations would be gratefully accepted for inclusion into the
  13 future versions of the library!
  14
  15 The wxWidgets approach to i18n closely follows GNU gettext package. wxWidgets uses the
  16 message catalogs which are binary compatible with gettext catalogs and this
  17 allows to use all of the programs in this package to work with them. But note
  18 that no additional libraries are needed during the run-time, however, so you
  19 have only the message catalogs to distribute and nothing else.
  20
  21 During program development you will need the gettext package for
  22 working with message catalogs. {\bf Warning:} gettext versions < 0.10 are known
  23 to be buggy, so you should find a later version of it!
  24
  25 There are two kinds of message catalogs: source catalogs which are text files
  26 with extension .po and binary catalogs which are created from the source ones
  27 with {\it msgfmt} program (part of gettext package) and have the extension .mo.
  28 Only the binary files are needed during program execution.
  29
  30 The program i18n involves several steps:
  31
  32 \begin{enumerate}\itemsep=0pt
  33 \item Translating the strings in the program text using
  34 \helpref{wxGetTranslation}{wxgettranslation} or equivalently the
  35 \helpref{\_()}{underscore} macro.
  36 \item Extracting the strings to be translated from the program: this uses the
  37 work done in the previous step because {\tt xgettext} program used for string
  38 extraction recognises the standard \_() as well as (using its {\tt -k} option)
  39 our wxGetTranslation and extracts all strings inside the calls to these
  40 functions. Alternatively, you may use {\tt -a} option to extract all the
  41 strings, but it will usually result in many strings being found which don't
  42 have to be translated at all. This will create a text message catalog -- a .po
  43 file.
  44 \item Translating the strings extracted in the previous step to other
  45 language(s). It involves editing the .po file.
  46 \item Compiling the .po file into .mo file to be used by the program.
  47 \item Setting the appropriate locale in your program to use the strings for the
  48 given language: see \helpref{wxLocale}{wxlocale}.
  49 \end{enumerate}
  50
  51 If you want your app to run under MacOS X with internationlization as
  52 described above you'll need to make one modification to the Info.plist
  53 file which describes the contents of the "application bundle". This
  54 file (an XML text file in UTF-8 format) should have a
  55 CFBundleDevelopmentRegion entry describing the language of the developer
  56 - mostly English - and normally MacOS X will query the bundle for the
  57 presence of certain resource directories to find out which languages
  58 are supported (e.g. the directory German.lproj for German).
  59 Since wxWidgets based applications don't use these directories
  60 for storing resource information (they store the translation in the
  61 mo files instead) the application needs to be told explicitly which
  62 langauges are supported. This is done by adding a CFBundleLocalizations
  63 entry to Info.plist. This can look like this:
  64
  65 \begin{verbatim}
  66         <key>CFBundleDevelopmentRegion</key>
  67         <string>English</string>
  68         <key>CFBundleLocalizations</key>
  69         <array>
  70                 <string>en</string>
  71                 <string>de</string>
  72                 <string>fr</string>
  73         </array>
  74 \end{verbatim}
  75
  76 See also the GNU gettext documentation linked from {\tt docs/html/index.htm} in
  77 your wxWidgets distribution.
  78
  79 See also \helpref{Writing non-English applications}{nonenglishoverview}.
  80 It focuses on handling charsets related problems.
  81
  82 Finally, take a look at the \helpref{i18n sample}{sampleinternat} which shows
  83 to you how all this looks in practice.
  84