X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/457e6c54a28bc20cf347ba921755d7d5b296aa2a..65baafba0e8cd74f2264b7e2f7625ff5bea84864:/docs/latex/wx/tnoneng.tex?ds=sidebyside diff --git a/docs/latex/wx/tnoneng.tex b/docs/latex/wx/tnoneng.tex index e4b22730be..56e9147833 100644 --- a/docs/latex/wx/tnoneng.tex +++ b/docs/latex/wx/tnoneng.tex @@ -1,37 +1,38 @@ \section{Writing non-English applications}\label{nonenglishoverview} This article describes how to write applications that communicate with -user in language other than English. Unfortunately many languages use +the user in a language other than English. Unfortunately many languages use different charsets under Unix and Windows (and other platforms, to make -situation even more complicated). These charsets usually differ in so -many characters it is impossible to use same texts under all platforms. -wxWindows provide mechanism that helps you avoid distributing many +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 distribute only let's say iso8859-13 data +to this mechanism you can, for example, distribute only iso8859-13 data and it will be handled transparently under all systems. Please read \helpref{Internationalization}{internationalization} which -describes locales concept. +describes the locales concept. -Whereever in the following text {\it iso8859-2} and {\it windows-1250} are +In the following text, wherever {\it iso8859-2} and {\it windows-1250} are used, any encodings are meant and any encodings may be substituted there. \wxheading{Locales} -The best way how to ensure correctly displayed texts in GUI across platforms +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 message catalog (see +diacritics and put real messages into the message catalog (see \helpref{Internationalization}{internationalization}). -Standard .po file begins with a header like this: +A standard .po file begins with a header like this: \begin{verbatim} # SOME DESCRIPTIVE TITLE. # Copyright (C) YEAR Free Software Foundation, Inc. # FIRST AUTHOR , YEAR. # -#, fuzzy msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" @@ -44,19 +45,17 @@ msgstr "" "Content-Transfer-Encoding: ENCODING\n" \end{verbatim} -Notice these two lines: +Note this particular line: \begin{verbatim} -#, fuzzy "Content-Type: text/plain; charset=CHARSET\n" \end{verbatim} -The first tells {\it msgfmt} compiler not to include string "" (empty) -to compiled .mo catalog. Second one informs about charset used to write -translated messages. +It specifies the charset used by the catalog. All strings in the catalog +are encoded using this charset. -You have to do 2 things: fill-in proper charset information and delete -the {\tt fuzzy} line. Your .po file may look like this after doing so: +You have to fill in proper charset information. Your .po file may look like this +after doing so: \begin{verbatim} # SOME DESCRIPTIVE TITLE. @@ -72,49 +71,65 @@ msgstr "" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=iso8859-2\n" -"Content-Transfer-Encoding: ENCODING\n" +"Content-Transfer-Encoding: 8bit\n" \end{verbatim} -wxWindows is able to use this catalog under any supported platform -(although iso8859-2 is Unix encoding and is not understood by Windows). - -How is this done? When you tell wxLocale class to load message catalog that -contains the header (msgid "". Normal .mo catalogs do {\bf not} contain it, -you must remove the line with {\it fuzzy}!), it checks the charset. If the -charset is "alien" on the platform the program is currently running (e.g. -any of ISO encodings under Windows or CP12XX under Unix) it uses -\helpref{wxEncodingConverter::GetPlatformEquivalents}{wxencodingconvertergetplatformequivalents} -to obtain encoding that is more common on this platform and converts -the message catalog to this encoding. Note that it does {\bf not} check -for presence of this encoding! It only assumes that it is always better to -have strings in platform native encoding than in an encoding that is rarely -(if ever) used. - -The behaviour described about is disabled by default. -You must set {\it bConvertEncoding} to TRUE in -\helpref{wxLocale constructor}{wxlocaledefctor} in order to enable -runtime encoding conversion! +(Make sure that the header is {\bf not} marked as {\it 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 +\helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding} and +\helpref{wxLocale::GetSystemEncodingName}{wxlocalegetsystemencodingname}) by +the user's operating system. This is the default behaviour of the +\helpref{wxLocale}{wxlocale} class; you can disable it by {\bf not} passing +{\tt wxLOCALE\_CONV\_ENCODING} to \helpref{wxLocale::Init}{wxlocaleinit}. + +\wxheading{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: + +\begin{enumerate} +\item{If you use the program {\tt xgettext} to extract the strings from +the source code, specify the option {\tt --from-code=}.} +\item{Specify the source code language and charset as arguments to +\helpref{wxLocale::AddCatalog}{wxlocaleaddcatalog}. For example: +\begin{verbatim} +locale.AddCatalog(_T("myapp"), + wxLANGUAGE_GERMAN, _T("iso-8859-1")); +\end{verbatim} +} +\end{enumerate} \wxheading{Font mapping} -You can use \helpref{wxEncodingConverter}{wxencodingconverter} and +You can use \helpref{wxMBConv classes}{mbconvclasses} and \helpref{wxFontMapper}{wxfontmapper} to display text: \begin{verbatim} -if (!wxTheFontMapper->IsEncodingAvailable(enc, facename)) +if (!wxFontMapper::Get()->IsEncodingAvailable(enc, facename)) { wxFontEncoding alternative; - if (wxTheFontMapper->GetAltForEncoding(enc, &alternative, - facename, FALSE)) + if (wxFontMapper::Get()->GetAltForEncoding(enc, &alternative, + facename, false)) { - wxEncodingConverted encconv; - if (!encconv.Init(enc, alternative)) - ...failure... - else - text = encconv.Convert(text); + wxCSConv convFrom(wxFontMapper::Get()->GetEncodingName(enc)); + wxCSConv convTo(wxFontMapper::Get()->GetEncodingName(alternative)); + text = wxString(text.mb_str(convFrom), convTo); } else - ...failure... + ...failure (or we may try iso8859-1/7bit ASCII)... } ...display text... \end{verbatim} @@ -122,26 +137,28 @@ if (!wxTheFontMapper->IsEncodingAvailable(enc, facename)) \wxheading{Converting data} You may want to store all program data (created documents etc.) in -same encoding, let's say windows1250. Obviously, the best way would -be to use \helpref{wxEncodingConverter}{wxencodingconverter}. +the same encoding, let's say {\tt utf-8}. You can use +\helpref{wxCSConv}{wxcsconv} class to convert data to the encoding used by the +system your application is running on (see +\helpref{wxLocale::GetSystemEncoding}{wxlocalegetsystemencoding}). \wxheading{Help files} If you're using \helpref{wxHtmlHelpController}{wxhtmlhelpcontroller} there is -no problem at all. You must only make sure that all HTML files contain -META tag, e.g. +no problem at all. You only need to make sure that all the HTML files contain +the META tag, e.g. \begin{verbatim} - + \end{verbatim} -and that hhp project file contains one additional line in {\tt OPTIONS} +and that the hhp project file contains one additional line in the {\tt OPTIONS} section: \begin{verbatim} Charset=iso8859-2 \end{verbatim} -This additional entry tells HTML help controller what encoding is used +This additional entry tells the HTML help controller what encoding is used in contents and index tables.