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