diff options
Diffstat (limited to 'doc/gettext_10.html')
-rw-r--r-- | doc/gettext_10.html | 139 |
1 files changed, 102 insertions, 37 deletions
diff --git a/doc/gettext_10.html b/doc/gettext_10.html index 81861b6..9015f50 100644 --- a/doc/gettext_10.html +++ b/doc/gettext_10.html @@ -1,16 +1,16 @@ <HTML> <HEAD> <!-- This HTML file has been created by texi2html 1.52a - from gettext.texi on 31 January 2002 --> + from gettext.texi on 7 March 2002 --> <TITLE>GNU gettext utilities - 10 The Programmer's View</TITLE> </HEAD> <BODY> -Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_9.html">previous</A>, <A HREF="gettext_11.html">next</A>, <A HREF="gettext_16.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. +Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_9.html">previous</A>, <A HREF="gettext_11.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. <P><HR><P> -<H1><A NAME="SEC138" HREF="gettext_toc.html#TOC138">10 The Programmer's View</A></H1> +<H1><A NAME="SEC140" HREF="gettext_toc.html#TOC140">10 The Programmer's View</A></H1> <P> One aim of the current message catalog implementation provided by @@ -28,8 +28,11 @@ later explain our solution of this dilemma. -<H2><A NAME="SEC139" HREF="gettext_toc.html#TOC139">10.1 About <CODE>catgets</CODE></A></H2> +<H2><A NAME="SEC141" HREF="gettext_toc.html#TOC141">10.1 About <CODE>catgets</CODE></A></H2> +<P> +<A NAME="IDX798"></A> +</P> <P> The <CODE>catgets</CODE> implementation is defined in the X/Open Portability Guide, Volume 3, XSI Supplementary Definitions, Chapter 5. But the @@ -60,8 +63,11 @@ therefore part of all Unix implementation (implementations, which are -<H3><A NAME="SEC140" HREF="gettext_toc.html#TOC140">10.1.1 The Interface</A></H3> +<H3><A NAME="SEC142" HREF="gettext_toc.html#TOC142">10.1.1 The Interface</A></H3> +<P> +<A NAME="IDX799"></A> +</P> <P> The interface to the <CODE>catgets</CODE> implementation consists of three functions which correspond to those used in file access: <CODE>catopen</CODE> @@ -72,6 +78,7 @@ for the functions and the needed definitions are in the </P> <P> +<A NAME="IDX800"></A> <CODE>catopen</CODE> is used like in this: </P> @@ -90,6 +97,7 @@ message catalog, equivalent to handles to file returned by <CODE>open</CODE>. </P> <P> +<A NAME="IDX801"></A> This handle is of course used in the <CODE>catgets</CODE> function which can be used like this: @@ -121,6 +129,7 @@ should better be <CODE>const char *</CODE>, but the standard is published in </P> <P> +<A NAME="IDX802"></A> The last of these function functions is used and behaves as expected: </P> @@ -135,11 +144,14 @@ After this no <CODE>catgets</CODE> call using the descriptor is legal anymore. </P> -<H3><A NAME="SEC141" HREF="gettext_toc.html#TOC141">10.1.2 Problems with the <CODE>catgets</CODE> Interface?!</A></H3> +<H3><A NAME="SEC143" HREF="gettext_toc.html#TOC143">10.1.2 Problems with the <CODE>catgets</CODE> Interface?!</A></H3> +<P> +<A NAME="IDX803"></A> +</P> <P> Now that this description seemed to be really easy -- where are the -problem we speak of? In fact the interface could be used in a +problems we speak of? In fact the interface could be used in a reasonable way, but constructing the message catalogs is a pain. The reason for this lies in the third argument of <CODE>catgets</CODE>: the unique message ID. This has to be a numeric value for all messages in a single @@ -153,8 +165,11 @@ more easy to manage. </P> -<H2><A NAME="SEC142" HREF="gettext_toc.html#TOC142">10.2 About <CODE>gettext</CODE></A></H2> +<H2><A NAME="SEC144" HREF="gettext_toc.html#TOC144">10.2 About <CODE>gettext</CODE></A></H2> +<P> +<A NAME="IDX804"></A> +</P> <P> The definition of the <CODE>gettext</CODE> interface comes from a Uniforum proposal and it is followed by at least one major Unix vendor @@ -167,7 +182,7 @@ The main points about this solution is that it does not follow the method of normal file handling (open-use-close) and that it does not burden the programmer so many task, especially the unique key handling. Of course here also a unique key is needed, but this key is the message -itself (how long or short it is). See section <A HREF="gettext_10.html#SEC150">10.3 Comparing the Two Interfaces</A> for a more +itself (how long or short it is). See section <A HREF="gettext_10.html#SEC152">10.3 Comparing the Two Interfaces</A> for a more detailed comparison of the two methods. </P> @@ -181,8 +196,11 @@ in using this library will be interested in this description. -<H3><A NAME="SEC143" HREF="gettext_toc.html#TOC143">10.2.1 The Interface</A></H3> +<H3><A NAME="SEC145" HREF="gettext_toc.html#TOC145">10.2.1 The Interface</A></H3> +<P> +<A NAME="IDX805"></A> +</P> <P> The minimal functionality an interface must have is a) to select a domain the strings are coming from (a single domain for all programs is @@ -249,8 +267,13 @@ your language. </P> -<H3><A NAME="SEC144" HREF="gettext_toc.html#TOC144">10.2.2 Solving Ambiguities</A></H3> +<H3><A NAME="SEC146" HREF="gettext_toc.html#TOC146">10.2.2 Solving Ambiguities</A></H3> +<P> +<A NAME="IDX806"></A> +<A NAME="IDX807"></A> +<A NAME="IDX808"></A> +</P> <P> While this single name domain works well for most applications there might be the need to get translations from more than one domain. Of @@ -322,8 +345,11 @@ unreliabilities. </P> -<H3><A NAME="SEC145" HREF="gettext_toc.html#TOC145">10.2.3 Locating Message Catalog Files</A></H3> +<H3><A NAME="SEC147" HREF="gettext_toc.html#TOC147">10.2.3 Locating Message Catalog Files</A></H3> +<P> +<A NAME="IDX809"></A> +</P> <P> Because many different languages for many different packages have to be stored we need some way to add these information to file message catalog @@ -359,8 +385,12 @@ The value of the locale is determined through </P> -<H3><A NAME="SEC146" HREF="gettext_toc.html#TOC146">10.2.4 How to specify the output character set <CODE>gettext</CODE> uses</A></H3> +<H3><A NAME="SEC148" HREF="gettext_toc.html#TOC148">10.2.4 How to specify the output character set <CODE>gettext</CODE> uses</A></H3> +<P> +<A NAME="IDX810"></A> +<A NAME="IDX811"></A> +</P> <P> <CODE>gettext</CODE> not only looks up a translation in a message catalog. It also converts the translation on the fly to the desired output character @@ -390,7 +420,7 @@ recommended that all <VAR>msgid</VAR>s be US-ASCII strings. <P> <DL> <DT><U>Function:</U> char * <B>bind_textdomain_codeset</B> <I>(const char *<VAR>domainname</VAR>, const char *<VAR>codeset</VAR>)</I> -<DD><A NAME="IDX1"></A> +<DD><A NAME="IDX812"></A> The <CODE>bind_textdomain_codeset</CODE> function can be used to specify the output character set for message catalogs for domain <VAR>domainname</VAR>. The <VAR>codeset</VAR> argument must be a valid codeset name which can be used @@ -422,8 +452,11 @@ global variable <VAR>errno</VAR> is set accordingly. </P> -<H3><A NAME="SEC147" HREF="gettext_toc.html#TOC147">10.2.5 Additional functions for plural forms</A></H3> +<H3><A NAME="SEC149" HREF="gettext_toc.html#TOC149">10.2.5 Additional functions for plural forms</A></H3> +<P> +<A NAME="IDX813"></A> +</P> <P> The functions of the <CODE>gettext</CODE> family described so far (and all the <CODE>catgets</CODE> functions as well) have one problem in the real world @@ -493,7 +526,7 @@ language families); <UL> <LI> -The form how plural forms are build differs. This is a problem with +The form how plural forms are built differs. This is a problem with languages which have many irregularities. German, for instance, is a drastic case. Though English and German are part of the same language family (Germanic), the almost regular forming of plural noun forms @@ -541,7 +574,7 @@ purpose. <P> <DL> <DT><U>Function:</U> char * <B>ngettext</B> <I>(const char *<VAR>msgid1</VAR>, const char *<VAR>msgid2</VAR>, unsigned long int <VAR>n</VAR>)</I> -<DD><A NAME="IDX2"></A> +<DD><A NAME="IDX814"></A> The <CODE>ngettext</CODE> function is similar to the <CODE>gettext</CODE> function as it finds the message catalogs in the same way. But it takes two extra arguments. The <VAR>msgid1</VAR> parameter must contain the singular @@ -571,7 +604,7 @@ Please note that the numeric value <VAR>n</VAR> has to be passed to the <P> <DL> <DT><U>Function:</U> char * <B>dngettext</B> <I>(const char *<VAR>domain</VAR>, const char *<VAR>msgid1</VAR>, const char *<VAR>msgid2</VAR>, unsigned long int <VAR>n</VAR>)</I> -<DD><A NAME="IDX3"></A> +<DD><A NAME="IDX815"></A> The <CODE>dngettext</CODE> is similar to the <CODE>dgettext</CODE> function in the way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two @@ -582,7 +615,7 @@ parameters are handled in the same way <CODE>ngettext</CODE> handles them. <P> <DL> <DT><U>Function:</U> char * <B>dcngettext</B> <I>(const char *<VAR>domain</VAR>, const char *<VAR>msgid1</VAR>, const char *<VAR>msgid2</VAR>, unsigned long int <VAR>n</VAR>, int <VAR>category</VAR>)</I> -<DD><A NAME="IDX4"></A> +<DD><A NAME="IDX816"></A> The <CODE>dcngettext</CODE> is similar to the <CODE>dcgettext</CODE> function in the way the message catalog is selected. The difference is that it takes two extra parameter to provide the correct plural form. These two @@ -607,6 +640,9 @@ possibility of extensions to not prevent the use of new languages). </P> <P> +<A NAME="IDX817"></A> +<A NAME="IDX818"></A> +<A NAME="IDX819"></A> The information about the plural form selection has to be stored in the header entry of the PO file (the one with the empty <CODE>msgid</CODE> string). The plural form information looks like this: @@ -632,6 +668,7 @@ value of <CODE>nplurals</CODE>. </P> <P> +<A NAME="IDX820"></A> The following rules are known at this point. The language with families are listed. But this does not necessarily mean the information can be generalized for the whole family (as can be easily seen in the table @@ -839,8 +876,13 @@ Slovenian -<H3><A NAME="SEC148" HREF="gettext_toc.html#TOC148">10.2.6 How to use <CODE>gettext</CODE> in GUI programs</A></H3> +<H3><A NAME="SEC150" HREF="gettext_toc.html#TOC150">10.2.6 How to use <CODE>gettext</CODE> in GUI programs</A></H3> +<P> +<A NAME="IDX821"></A> +<A NAME="IDX822"></A> +<A NAME="IDX823"></A> +</P> <P> One place where the <CODE>gettext</CODE> functions, if used normally, have big problems is within programs with graphical user interfaces (GUIs). The @@ -915,7 +957,7 @@ fine: </P> <P> -<A NAME="IDX5"></A> +<A NAME="IDX824"></A> <PRE> char * @@ -990,8 +1032,11 @@ quite some memory and disk space by doing this. </P> -<H3><A NAME="SEC149" HREF="gettext_toc.html#TOC149">10.2.7 Optimization of the *gettext functions</A></H3> +<H3><A NAME="SEC151" HREF="gettext_toc.html#TOC151">10.2.7 Optimization of the *gettext functions</A></H3> +<P> +<A NAME="IDX825"></A> +</P> <P> At this point of the discussion we should talk about an advantage of the GNU <CODE>gettext</CODE> implementation. Some readers might have pointed out @@ -1042,7 +1087,12 @@ find the result through a single cache lookup. </P> -<H2><A NAME="SEC150" HREF="gettext_toc.html#TOC150">10.3 Comparing the Two Interfaces</A></H2> +<H2><A NAME="SEC152" HREF="gettext_toc.html#TOC152">10.3 Comparing the Two Interfaces</A></H2> +<P> +<A NAME="IDX826"></A> +<A NAME="IDX827"></A> + +</P> <P> The following discussion is perhaps a little bit colored. As said @@ -1089,6 +1139,8 @@ the definition by </P> +<P> +<A NAME="IDX828"></A> <PRE> #include <libintl.h> @@ -1103,6 +1155,7 @@ can use any that becomes available. </P> <P> +<A NAME="IDX829"></A> The same procedure can be done for the <CODE>gettext_noop</CODE> invocations (see section <A HREF="gettext_3.html#SEC18">3.5 Special Cases of Translatable Strings</A>). One usually defines <CODE>gettext_noop</CODE> as a no-op macro. So you should consider the following code for your project: @@ -1181,12 +1234,12 @@ little bit. But it is not impossible to overcome. <P> <CODE>catgets</CODE> allows same original entry to have different translations, but <CODE>gettext</CODE> has another, scalable approach for solving ambiguities -of this kind: See section <A HREF="gettext_10.html#SEC144">10.2.2 Solving Ambiguities</A>. +of this kind: See section <A HREF="gettext_10.html#SEC146">10.2.2 Solving Ambiguities</A>. </P> -<H2><A NAME="SEC151" HREF="gettext_toc.html#TOC151">10.4 Using libintl.a in own programs</A></H2> +<H2><A NAME="SEC153" HREF="gettext_toc.html#TOC153">10.4 Using libintl.a in own programs</A></H2> <P> Starting with version 0.9.4 the library <CODE>libintl.h</CODE> should be @@ -1197,7 +1250,7 @@ and the library in directories selected using the <CODE>$(prefix)</CODE>. </P> -<H2><A NAME="SEC152" HREF="gettext_toc.html#TOC152">10.5 Being a <CODE>gettext</CODE> grok</A></H2> +<H2><A NAME="SEC154" HREF="gettext_toc.html#TOC154">10.5 Being a <CODE>gettext</CODE> grok</A></H2> <P> To fully exploit the functionality of the GNU <CODE>gettext</CODE> library it @@ -1210,6 +1263,8 @@ is a list comments: <UL> <LI>Changing the language at runtime +<A NAME="IDX830"></A> + For interactive programs it might be useful to offer a selection of the used language at runtime. To understand how to do this one need to know how the used language is determined while executing the <CODE>gettext</CODE> @@ -1225,10 +1280,20 @@ priority: <OL> <LI><CODE>LANGUAGE</CODE> +<A NAME="IDX831"></A> + +<A NAME="IDX832"></A> <LI><CODE>LC_ALL</CODE> +<A NAME="IDX833"></A> +<A NAME="IDX834"></A> +<A NAME="IDX835"></A> +<A NAME="IDX836"></A> +<A NAME="IDX837"></A> +<A NAME="IDX838"></A> <LI><CODE>LC_xxx</CODE>, according to selected locale +<A NAME="IDX839"></A> <LI><CODE>LANG</CODE> </OL> @@ -1246,7 +1311,7 @@ But there is one little hook. The code for gcc-2.7.0 and up provides some optimization. This optimization normally prevents the calling of the <CODE>dcgettext</CODE> function as long as no new catalog is loaded. But if <CODE>dcgettext</CODE> is not called the program also cannot find the -<CODE>LANGUAGE</CODE> variable be changed (see section <A HREF="gettext_10.html#SEC149">10.2.7 Optimization of the *gettext functions</A>). A +<CODE>LANGUAGE</CODE> variable be changed (see section <A HREF="gettext_10.html#SEC151">10.2.7 Optimization of the *gettext functions</A>). A solution for this is very easy. Include the following code in the language switching function. @@ -1262,21 +1327,21 @@ language switching function. } </PRE> +<A NAME="IDX840"></A> The variable <CODE>_nl_msg_cat_cntr</CODE> is defined in <TT>`loadmsgcat.c´</TT>. -The programmer will find himself in need for a construct like this only -when developing programs which do run longer and provide the user to -select the language at runtime. Non-interactive programs (like all -these little Unix tools) should never need this. +You don't need to know what this is for. But it can be used to detect +whether a <CODE>gettext</CODE> implementation is GNU gettext and not non-GNU +system's native gettext implementation. </UL> -<H2><A NAME="SEC153" HREF="gettext_toc.html#TOC153">10.6 Temporary Notes for the Programmers Chapter</A></H2> +<H2><A NAME="SEC155" HREF="gettext_toc.html#TOC155">10.6 Temporary Notes for the Programmers Chapter</A></H2> -<H3><A NAME="SEC154" HREF="gettext_toc.html#TOC154">10.6.1 Temporary - Two Possible Implementations</A></H3> +<H3><A NAME="SEC156" HREF="gettext_toc.html#TOC156">10.6.1 Temporary - Two Possible Implementations</A></H3> <P> There are two competing methods for language independent messages: @@ -1308,7 +1373,7 @@ see the Programming for Internationalization FAQ. </P> -<H3><A NAME="SEC155" HREF="gettext_toc.html#TOC155">10.6.2 Temporary - About <CODE>catgets</CODE></A></H3> +<H3><A NAME="SEC157" HREF="gettext_toc.html#TOC157">10.6.2 Temporary - About <CODE>catgets</CODE></A></H3> <P> There have been a few discussions of late on the use of @@ -1353,7 +1418,7 @@ of all Unix systems. </P> -<H3><A NAME="SEC156" HREF="gettext_toc.html#TOC156">10.6.3 Temporary - Why a single implementation</A></H3> +<H3><A NAME="SEC158" HREF="gettext_toc.html#TOC158">10.6.3 Temporary - Why a single implementation</A></H3> <P> Now it seems kind of wasteful to me to have two different systems @@ -1398,7 +1463,7 @@ the future. </P> -<H3><A NAME="SEC157" HREF="gettext_toc.html#TOC157">10.6.4 Temporary - Notes</A></H3> +<H3><A NAME="SEC159" HREF="gettext_toc.html#TOC159">10.6.4 Temporary - Notes</A></H3> <P> X/Open agreed very late on the standard form so that many @@ -1413,6 +1478,6 @@ Solaris is not the only system having <CODE>gettext</CODE>. </P> <P><HR><P> -Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_9.html">previous</A>, <A HREF="gettext_11.html">next</A>, <A HREF="gettext_16.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. +Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_9.html">previous</A>, <A HREF="gettext_11.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. </BODY> </HTML> |