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