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