More doxygen topic overview cleanup.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52211 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
@@ -1,5 +1,5 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: nonenglish
|
||||
// Name: nonenglish.h
|
||||
// Purpose: topic overview
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
@@ -8,156 +8,161 @@
|
||||
|
||||
/*!
|
||||
|
||||
@page nonenglish_overview Writing non-English applications
|
||||
@page overview_nonenglish Writing Non-English Applications
|
||||
|
||||
This article describes how to write applications that communicate with
|
||||
the user in a language other than English. Unfortunately many languages use
|
||||
different charsets under Unix and Windows (and other platforms, to make
|
||||
the situation even more complicated). These charsets usually differ in so
|
||||
many characters that it is impossible to use the same texts under all
|
||||
platforms.
|
||||
The wxWidgets library provides a mechanism that helps you avoid distributing many
|
||||
identical, only differently encoded, packages with your application
|
||||
(e.g. help files and menu items in iso8859-13 and windows-1257). Thanks
|
||||
to this mechanism you can, for example, distribute only iso8859-13 data
|
||||
and it will be handled transparently under all systems.
|
||||
Please read #Internationalization which
|
||||
describes the locales concept.
|
||||
In the following text, wherever @e iso8859-2 and @e windows-1250 are
|
||||
used, any encodings are meant and any encodings may be substituted there.
|
||||
@b Locales
|
||||
The best way to ensure correctly displayed texts in a GUI across platforms
|
||||
is to use locales. Write your in-code messages in English or without
|
||||
diacritics and put real messages into the message catalog (see
|
||||
#Internationalization).
|
||||
A standard .po file begins with a header like this:
|
||||
This article describes how to write applications that communicate with the user
|
||||
in a language other than English. Unfortunately many languages use different
|
||||
charsets under Unix and Windows (and other platforms, to make the situation
|
||||
even more complicated). These charsets usually differ in so many characters
|
||||
that it is impossible to use the same texts under all platforms.
|
||||
|
||||
@code
|
||||
# SOME DESCRIPTIVE TITLE.
|
||||
# Copyright (C) YEAR Free Software Foundation, Inc.
|
||||
# FIRST AUTHOR EMAIL@ADDRESS, YEAR.
|
||||
#
|
||||
msgid ""
|
||||
msgstr ""
|
||||
"Project-Id-Version: PACKAGE VERSION\n"
|
||||
"POT-Creation-Date: 1999-02-19 16:03+0100\n"
|
||||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||||
"Last-Translator: FULL NAME EMAIL@ADDRESS\n"
|
||||
"Language-Team: LANGUAGE LL@li.org\n"
|
||||
"MIME-Version: 1.0\n"
|
||||
"Content-Type: text/plain; charset=CHARSET\n"
|
||||
"Content-Transfer-Encoding: ENCODING\n"
|
||||
@endcode
|
||||
The wxWidgets library provides a mechanism that helps you avoid distributing
|
||||
many identical, only differently encoded, packages with your application (e.g.
|
||||
help files and menu items in iso8859-13 and windows-1257). Thanks to this
|
||||
mechanism you can, for example, distribute only iso8859-13 data and it will be
|
||||
handled transparently under all systems.
|
||||
|
||||
Note this particular line:
|
||||
Please read the @ref overview_i18n which describes the locales concept.
|
||||
|
||||
@code
|
||||
"Content-Type: text/plain; charset=CHARSET\n"
|
||||
@endcode
|
||||
|
||||
It specifies the charset used by the catalog. All strings in the catalog
|
||||
are encoded using this charset.
|
||||
You have to fill in proper charset information. Your .po file may look like this
|
||||
after doing so:
|
||||
|
||||
@code
|
||||
# SOME DESCRIPTIVE TITLE.
|
||||
# Copyright (C) YEAR Free Software Foundation, Inc.
|
||||
# FIRST AUTHOR EMAIL@ADDRESS, YEAR.
|
||||
#
|
||||
msgid ""
|
||||
msgstr ""
|
||||
"Project-Id-Version: PACKAGE VERSION\n"
|
||||
"POT-Creation-Date: 1999-02-19 16:03+0100\n"
|
||||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||||
"Last-Translator: FULL NAME EMAIL@ADDRESS\n"
|
||||
"Language-Team: LANGUAGE LL@li.org\n"
|
||||
"MIME-Version: 1.0\n"
|
||||
"Content-Type: text/plain; charset=iso8859-2\n"
|
||||
"Content-Transfer-Encoding: 8bit\n"
|
||||
@endcode
|
||||
|
||||
(Make sure that the header is @b not marked as @e fuzzy.)
|
||||
wxWidgets is able to use this catalog under any supported platform
|
||||
(although iso8859-2 is a Unix encoding and is normally not understood by
|
||||
Windows).
|
||||
How is this done? When you tell the wxLocale class to load a message catalog that
|
||||
contains a correct header, it checks the charset. The catalog is then converted
|
||||
to the charset used (see
|
||||
wxLocale::GetSystemEncoding and
|
||||
wxLocale::GetSystemEncodingName) by
|
||||
the user's operating system. This is the default behaviour of the
|
||||
#wxLocale class; you can disable it by @b not passing
|
||||
@c wxLOCALE_CONV_ENCODING to wxLocale::Init.
|
||||
@b Non-English strings or 8-bit characters in the source code
|
||||
By convention, you should only use characters without diacritics (i.e. 7-bit
|
||||
ASCII strings) for msgids in the source code and write them in English.
|
||||
If you port software to wxWindows, you may be confronted with legacy source
|
||||
code containing non-English string literals. Instead of translating the strings
|
||||
in the source code to English and putting the original strings into message
|
||||
catalog, you may configure wxWidgets to use non-English msgids and translate to
|
||||
English using message catalogs:
|
||||
In the following text, wherever @e iso8859-2 and @e windows-1250 are used, any
|
||||
encodings are meant and any encodings may be substituted there.
|
||||
|
||||
|
||||
If you use the program @c xgettext to extract the strings from
|
||||
the source code, specify the option @c --from-code=source code charset.
|
||||
Specify the source code language and charset as arguments to
|
||||
wxLocale::AddCatalog. For example:
|
||||
@section overview_nonenglish_locales Locales
|
||||
|
||||
@code
|
||||
locale.AddCatalog(_T("myapp"),
|
||||
wxLANGUAGE_GERMAN, _T("iso-8859-1"));
|
||||
@endcode
|
||||
The best way to ensure correctly displayed texts in a GUI across platforms is
|
||||
to use locales. Write your in-code messages in English or without diacritics
|
||||
and put real messages into the message catalog (see @ref overview_i18n).
|
||||
|
||||
A standard .po file begins with a header like this:
|
||||
|
||||
@code
|
||||
# SOME DESCRIPTIVE TITLE.
|
||||
# Copyright (C) YEAR Free Software Foundation, Inc.
|
||||
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
||||
#
|
||||
msgid ""
|
||||
msgstr ""
|
||||
"Project-Id-Version: PACKAGE VERSION\n"
|
||||
"POT-Creation-Date: 1999-02-19 16:03+0100\n"
|
||||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||||
"Language-Team: LANGUAGE <LL@li.org>\n"
|
||||
"MIME-Version: 1.0\n"
|
||||
"Content-Type: text/plain; charset=CHARSET\n"
|
||||
"Content-Transfer-Encoding: ENCODING\n"
|
||||
@endcode
|
||||
|
||||
Note this particular line:
|
||||
|
||||
@code
|
||||
"Content-Type: text/plain; charset=CHARSET\n"
|
||||
@endcode
|
||||
|
||||
It specifies the charset used by the catalog. All strings in the catalog are
|
||||
encoded using this charset.
|
||||
|
||||
You have to fill in proper charset information. Your .po file may look like
|
||||
this after doing so:
|
||||
|
||||
@code
|
||||
# SOME DESCRIPTIVE TITLE.
|
||||
# Copyright (C) YEAR Free Software Foundation, Inc.
|
||||
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
||||
#
|
||||
msgid ""
|
||||
msgstr ""
|
||||
"Project-Id-Version: PACKAGE VERSION\n"
|
||||
"POT-Creation-Date: 1999-02-19 16:03+0100\n"
|
||||
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
||||
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
||||
"Language-Team: LANGUAGE <LL@li.org>\n"
|
||||
"MIME-Version: 1.0\n"
|
||||
"Content-Type: text/plain; charset=iso8859-2\n"
|
||||
"Content-Transfer-Encoding: 8bit\n"
|
||||
@endcode
|
||||
|
||||
(Make sure that the header is @b not marked as @e fuzzy.)
|
||||
|
||||
wxWidgets is able to use this catalog under any supported platform
|
||||
(although iso8859-2 is a Unix encoding and is normally not understood by
|
||||
Windows).
|
||||
|
||||
How is this done? When you tell the wxLocale class to load a message catalog
|
||||
that contains a correct header, it checks the charset. The catalog is then
|
||||
converted to the charset used (see wxLocale::GetSystemEncoding and
|
||||
wxLocale::GetSystemEncodingName) by the user's operating system. This is the
|
||||
default behaviour of the wxLocale class; you can disable it by @b not passing
|
||||
@c wxLOCALE_CONV_ENCODING to wxLocale::Init.
|
||||
|
||||
|
||||
@section overview_nonenglish_strings Non-English Strings or 8-bit Characters in Source
|
||||
|
||||
By convention, you should only use characters without diacritics (i.e. 7-bit
|
||||
ASCII strings) for msgids in the source code and write them in English.
|
||||
|
||||
If you port software to wxWindows, you may be confronted with legacy source
|
||||
code containing non-English string literals. Instead of translating the strings
|
||||
in the source code to English and putting the original strings into message
|
||||
catalog, you may configure wxWidgets to use non-English msgids and translate to
|
||||
English using message catalogs:
|
||||
|
||||
@li If you use the program @c xgettext to extract the strings from the source
|
||||
code, specify the option <tt>--from-code=@<source code charset@></tt>.
|
||||
@li Specify the source code language and charset as arguments to
|
||||
wxLocale::AddCatalog. For example:
|
||||
@code
|
||||
locale.AddCatalog(_T("myapp"), wxLANGUAGE_GERMAN, _T("iso-8859-1"));
|
||||
@endcode
|
||||
|
||||
|
||||
@b Font mapping
|
||||
You can use @ref mbconvclasses_overview and
|
||||
#wxFontMapper to display text:
|
||||
@section overview_nonenglish_fontmapping Font Mapping
|
||||
|
||||
@code
|
||||
if (!wxFontMapper::Get()-IsEncodingAvailable(enc, facename))
|
||||
{
|
||||
You can use @ref overview_mbconv and wxFontMapper to display text:
|
||||
|
||||
@code
|
||||
if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename))
|
||||
{
|
||||
wxFontEncoding alternative;
|
||||
if (wxFontMapper::Get()-GetAltForEncoding(enc, ,
|
||||
facename, @false))
|
||||
if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative,
|
||||
facename, false))
|
||||
{
|
||||
wxCSConv convFrom(wxFontMapper::Get()-GetEncodingName(enc));
|
||||
wxCSConv convTo(wxFontMapper::Get()-GetEncodingName(alternative));
|
||||
wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc));
|
||||
wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative));
|
||||
text = wxString(text.mb_str(convFrom), convTo);
|
||||
}
|
||||
else
|
||||
...failure (or we may try iso8859-1/7bit ASCII)...
|
||||
}
|
||||
...display text...
|
||||
@endcode
|
||||
|
||||
@b Converting data
|
||||
You may want to store all program data (created documents etc.) in
|
||||
the same encoding, let's say @c utf-8. You can use
|
||||
#wxCSConv class to convert data to the encoding used by the
|
||||
system your application is running on (see
|
||||
wxLocale::GetSystemEncoding).
|
||||
@b Help files
|
||||
If you're using #wxHtmlHelpController there is
|
||||
no problem at all. You only need to make sure that all the HTML files contain
|
||||
the META tag, e.g.
|
||||
|
||||
@code
|
||||
meta http-equiv="Content-Type" content="text/html; charset=iso8859-2"
|
||||
@endcode
|
||||
|
||||
and that the hhp project file contains one additional line in the @c OPTIONS
|
||||
section:
|
||||
|
||||
@code
|
||||
Charset=iso8859-2
|
||||
@endcode
|
||||
|
||||
This additional entry tells the HTML help controller what encoding is used
|
||||
in contents and index tables.
|
||||
|
||||
*/
|
||||
}
|
||||
...display text...
|
||||
@endcode
|
||||
|
||||
|
||||
@section overview_nonenglish_converting Converting Data
|
||||
|
||||
You may want to store all program data (created documents etc.) in the same
|
||||
encoding, let's say @c utf-8. You can use wxCSConv to convert data to the
|
||||
encoding used by the system your application is running on (see
|
||||
wxLocale::GetSystemEncoding).
|
||||
|
||||
|
||||
@section overview_nonenglish_help Help Files
|
||||
|
||||
If you're using wxHtmlHelpController there is no problem at all. You only need
|
||||
to make sure that all the HTML files contain the META tag:
|
||||
|
||||
@code
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso8859-2">
|
||||
@endcode
|
||||
|
||||
Also, the hhp project file needs one additional line in the @c OPTIONS section:
|
||||
|
||||
@code
|
||||
Charset=iso8859-2
|
||||
@endcode
|
||||
|
||||
This additional entry tells the HTML help controller what encoding is used in
|
||||
contents and index tables.
|
||||
|
||||
*/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user