<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52b
- from gettext.texi on 7 January 2014 -->
+ from gettext.texi on 28 December 2015 -->
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
<TITLE>GNU gettext utilities - 11 The Programmer's View</TITLE>
<P><HR><P>
-<H1><A NAME="SEC178" HREF="gettext_toc.html#TOC178">11 The Programmer's View</A></H1>
+<H1><A NAME="SEC180" HREF="gettext_toc.html#TOC180">11 The Programmer's View</A></H1>
<P>
One aim of the current message catalog implementation provided by
-<H2><A NAME="SEC179" HREF="gettext_toc.html#TOC179">11.1 About <CODE>catgets</CODE></A></H2>
+<H2><A NAME="SEC181" HREF="gettext_toc.html#TOC181">11.1 About <CODE>catgets</CODE></A></H2>
<P>
-<A NAME="IDX1070"></A>
+<A NAME="IDX1109"></A>
</P>
<P>
-<H3><A NAME="SEC180" HREF="gettext_toc.html#TOC180">11.1.1 The Interface</A></H3>
+<H3><A NAME="SEC182" HREF="gettext_toc.html#TOC182">11.1.1 The Interface</A></H3>
<P>
-<A NAME="IDX1071"></A>
+<A NAME="IDX1110"></A>
</P>
<P>
</P>
<P>
-<A NAME="IDX1072"></A>
+<A NAME="IDX1111"></A>
<CODE>catopen</CODE> is used like in this:
</P>
</P>
<P>
-<A NAME="IDX1073"></A>
+<A NAME="IDX1112"></A>
This handle is of course used in the <CODE>catgets</CODE> function which can
be used like this:
</P>
<P>
-<A NAME="IDX1074"></A>
+<A NAME="IDX1113"></A>
The last of these functions is used and behaves as expected:
</P>
</P>
-<H3><A NAME="SEC181" HREF="gettext_toc.html#TOC181">11.1.2 Problems with the <CODE>catgets</CODE> Interface?!</A></H3>
+<H3><A NAME="SEC183" HREF="gettext_toc.html#TOC183">11.1.2 Problems with the <CODE>catgets</CODE> Interface?!</A></H3>
<P>
-<A NAME="IDX1075"></A>
+<A NAME="IDX1114"></A>
</P>
<P>
</P>
-<H2><A NAME="SEC182" HREF="gettext_toc.html#TOC182">11.2 About <CODE>gettext</CODE></A></H2>
+<H2><A NAME="SEC184" HREF="gettext_toc.html#TOC184">11.2 About <CODE>gettext</CODE></A></H2>
<P>
-<A NAME="IDX1076"></A>
+<A NAME="IDX1115"></A>
</P>
<P>
method of normal file handling (open-use-close) and that it does not
burden the programmer with so many tasks, 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_11.html#SEC190">11.3 Comparing the Two Interfaces</A> for a more
+itself (how long or short it is). See section <A HREF="gettext_11.html#SEC192">11.3 Comparing the Two Interfaces</A> for a more
detailed comparison of the two methods.
</P>
-<H3><A NAME="SEC183" HREF="gettext_toc.html#TOC183">11.2.1 The Interface</A></H3>
+<H3><A NAME="SEC185" HREF="gettext_toc.html#TOC185">11.2.1 The Interface</A></H3>
<P>
-<A NAME="IDX1077"></A>
+<A NAME="IDX1116"></A>
</P>
<P>
</P>
-<H3><A NAME="SEC184" HREF="gettext_toc.html#TOC184">11.2.2 Solving Ambiguities</A></H3>
+<H3><A NAME="SEC186" HREF="gettext_toc.html#TOC186">11.2.2 Solving Ambiguities</A></H3>
<P>
-<A NAME="IDX1078"></A>
-<A NAME="IDX1079"></A>
-<A NAME="IDX1080"></A>
+<A NAME="IDX1117"></A>
+<A NAME="IDX1118"></A>
+<A NAME="IDX1119"></A>
</P>
<P>
</P>
-<H3><A NAME="SEC185" HREF="gettext_toc.html#TOC185">11.2.3 Locating Message Catalog Files</A></H3>
+<H3><A NAME="SEC187" HREF="gettext_toc.html#TOC187">11.2.3 Locating Message Catalog Files</A></H3>
<P>
-<A NAME="IDX1081"></A>
+<A NAME="IDX1120"></A>
</P>
<P>
</P>
-<H3><A NAME="SEC186" HREF="gettext_toc.html#TOC186">11.2.4 How to specify the output character set <CODE>gettext</CODE> uses</A></H3>
+<H3><A NAME="SEC188" HREF="gettext_toc.html#TOC188">11.2.4 How to specify the output character set <CODE>gettext</CODE> uses</A></H3>
<P>
-<A NAME="IDX1082"></A>
-<A NAME="IDX1083"></A>
+<A NAME="IDX1121"></A>
+<A NAME="IDX1122"></A>
</P>
<P>
<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="IDX1084"></A>
+<DD><A NAME="IDX1123"></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
</P>
-<H3><A NAME="SEC187" HREF="gettext_toc.html#TOC187">11.2.5 Using contexts for solving ambiguities</A></H3>
+<H3><A NAME="SEC189" HREF="gettext_toc.html#TOC189">11.2.5 Using contexts for solving ambiguities</A></H3>
<P>
-<A NAME="IDX1085"></A>
-<A NAME="IDX1086"></A>
-<A NAME="IDX1087"></A>
-<A NAME="IDX1088"></A>
+<A NAME="IDX1124"></A>
+<A NAME="IDX1125"></A>
+<A NAME="IDX1126"></A>
+<A NAME="IDX1127"></A>
</P>
<P>
</P>
<P>
-<A NAME="IDX1089"></A>
+<A NAME="IDX1128"></A>
<PRE>
const char *pgettext (const char *msgctxt, const char *msgid);
</P>
<P>
-<A NAME="IDX1090"></A>
-<A NAME="IDX1091"></A>
+<A NAME="IDX1129"></A>
+<A NAME="IDX1130"></A>
<PRE>
const char *dpgettext (const char *domain_name,
</P>
<P>
-<A NAME="IDX1092"></A>
-<A NAME="IDX1093"></A>
-<A NAME="IDX1094"></A>
+<A NAME="IDX1131"></A>
+<A NAME="IDX1132"></A>
+<A NAME="IDX1133"></A>
<PRE>
const char *pgettext_expr (const char *msgctxt, const char *msgid);
</P>
-<H3><A NAME="SEC188" HREF="gettext_toc.html#TOC188">11.2.6 Additional functions for plural forms</A></H3>
+<H3><A NAME="SEC190" HREF="gettext_toc.html#TOC190">11.2.6 Additional functions for plural forms</A></H3>
<P>
-<A NAME="IDX1095"></A>
+<A NAME="IDX1134"></A>
</P>
<P>
<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="IDX1096"></A>
+<DD><A NAME="IDX1135"></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
</PRE>
<P>
-See section <A HREF="gettext_15.html#SEC249">15.3.1 C Format Strings</A> for details about this argument reordering syntax.
+See section <A HREF="gettext_15.html#SEC252">15.3.1 C Format Strings</A> for details about this argument reordering syntax.
</P>
<P>
<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="IDX1097"></A>
+<DD><A NAME="IDX1136"></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
<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="IDX1098"></A>
+<DD><A NAME="IDX1137"></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
</P>
<P>
-<A NAME="IDX1099"></A>
-<A NAME="IDX1100"></A>
-<A NAME="IDX1101"></A>
+<A NAME="IDX1138"></A>
+<A NAME="IDX1139"></A>
+<A NAME="IDX1140"></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:
</P>
<P>
-<A NAME="IDX1102"></A>
+<A NAME="IDX1141"></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
Japanese,
Vietnamese,
Korean
+<DT>Tai-Kadai family
+<DD>
+Thai
</DL>
<DT>Two forms, singular used for one only
<DT>Semitic family
<DD>
Hebrew
+<DT>Austronesian family
+<DD>
+Bahasa Indonesian
<DT>Artificial
<DD>
Esperanto
<DD>
Slovenian
</DL>
+
+<DT>Six forms, special cases for one, two, all numbers ending in 02, 03, ... 10, all numbers ending in 11 ... 99, and others
+<DD>
+The header entry would look like this:
+
+
+<PRE>
+Plural-Forms: nplurals=6; \
+ plural=n==0 ? 0 : n==1 ? 1 : n==2 ? 2 : n%100>=3 && n%100<=10 ? 3 \
+ : n%100>=11 ? 4 : 5;
+</PRE>
+
+Languages with this property include:
+
+<DL COMPACT>
+
+<DT>Afroasiatic family
+<DD>
+Arabic
+</DL>
</DL>
<P>
</P>
<P>
The translators' perspective regarding plural forms is explained in
-section <A HREF="gettext_12.html#SEC209">12.6 Translating plural forms</A>.
+section <A HREF="gettext_12.html#SEC211">12.6 Translating plural forms</A>.
</P>
-<H3><A NAME="SEC189" HREF="gettext_toc.html#TOC189">11.2.7 Optimization of the *gettext functions</A></H3>
+<H3><A NAME="SEC191" HREF="gettext_toc.html#TOC191">11.2.7 Optimization of the *gettext functions</A></H3>
<P>
-<A NAME="IDX1103"></A>
+<A NAME="IDX1142"></A>
</P>
<P>
</P>
-<H2><A NAME="SEC190" HREF="gettext_toc.html#TOC190">11.3 Comparing the Two Interfaces</A></H2>
+<H2><A NAME="SEC192" HREF="gettext_toc.html#TOC192">11.3 Comparing the Two Interfaces</A></H2>
<P>
-<A NAME="IDX1104"></A>
-<A NAME="IDX1105"></A>
+<A NAME="IDX1143"></A>
+<A NAME="IDX1144"></A>
</P>
</P>
<P>
-<A NAME="IDX1106"></A>
+<A NAME="IDX1145"></A>
<PRE>
#include <libintl.h>
</P>
<P>
-<A NAME="IDX1107"></A>
+<A NAME="IDX1146"></A>
The same procedure can be done for the <CODE>gettext_noop</CODE> invocations
(see section <A HREF="gettext_4.html#SEC23">4.7 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:
<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_11.html#SEC184">11.2.2 Solving Ambiguities</A>.
+of this kind: See section <A HREF="gettext_11.html#SEC186">11.2.2 Solving Ambiguities</A>.
</P>
-<H2><A NAME="SEC191" HREF="gettext_toc.html#TOC191">11.4 Using libintl.a in own programs</A></H2>
+<H2><A NAME="SEC193" HREF="gettext_toc.html#TOC193">11.4 Using libintl.a in own programs</A></H2>
<P>
Starting with version 0.9.4 the library <CODE>libintl.h</CODE> should be
</P>
-<H2><A NAME="SEC192" HREF="gettext_toc.html#TOC192">11.5 Being a <CODE>gettext</CODE> grok</A></H2>
+<H2><A NAME="SEC194" HREF="gettext_toc.html#TOC194">11.5 Being a <CODE>gettext</CODE> grok</A></H2>
<P>
<STRONG> NOTE: </STRONG> This documentation section is outdated and needs to be
<UL>
<LI>Changing the language at runtime
-<A NAME="IDX1108"></A>
+<A NAME="IDX1147"></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
<OL>
<LI><CODE>LANGUAGE</CODE>
-<A NAME="IDX1109"></A>
+<A NAME="IDX1148"></A>
-<A NAME="IDX1110"></A>
+<A NAME="IDX1149"></A>
<LI><CODE>LC_ALL</CODE>
-<A NAME="IDX1111"></A>
-<A NAME="IDX1112"></A>
-<A NAME="IDX1113"></A>
-<A NAME="IDX1114"></A>
-<A NAME="IDX1115"></A>
-<A NAME="IDX1116"></A>
+<A NAME="IDX1150"></A>
+<A NAME="IDX1151"></A>
+<A NAME="IDX1152"></A>
+<A NAME="IDX1153"></A>
+<A NAME="IDX1154"></A>
+<A NAME="IDX1155"></A>
<LI><CODE>LC_xxx</CODE>, according to selected locale category
-<A NAME="IDX1117"></A>
+<A NAME="IDX1156"></A>
<LI><CODE>LANG</CODE>
</OL>
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_11.html#SEC189">11.2.7 Optimization of the *gettext functions</A>). A
+<CODE>LANGUAGE</CODE> variable be changed (see section <A HREF="gettext_11.html#SEC191">11.2.7 Optimization of the *gettext functions</A>). A
solution for this is very easy. Include the following code in the
language switching function.
}
</PRE>
-<A NAME="IDX1118"></A>
+<A NAME="IDX1157"></A>
The variable <CODE>_nl_msg_cat_cntr</CODE> is defined in <TT>‘loadmsgcat.c’</TT>.
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
-<H2><A NAME="SEC193" HREF="gettext_toc.html#TOC193">11.6 Temporary Notes for the Programmers Chapter</A></H2>
+<H2><A NAME="SEC195" HREF="gettext_toc.html#TOC195">11.6 Temporary Notes for the Programmers Chapter</A></H2>
<P>
<STRONG> NOTE: </STRONG> This documentation section is outdated and needs to be
-<H3><A NAME="SEC194" HREF="gettext_toc.html#TOC194">11.6.1 Temporary - Two Possible Implementations</A></H3>
+<H3><A NAME="SEC196" HREF="gettext_toc.html#TOC196">11.6.1 Temporary - Two Possible Implementations</A></H3>
<P>
There are two competing methods for language independent messages:
</P>
-<H3><A NAME="SEC195" HREF="gettext_toc.html#TOC195">11.6.2 Temporary - About <CODE>catgets</CODE></A></H3>
+<H3><A NAME="SEC197" HREF="gettext_toc.html#TOC197">11.6.2 Temporary - About <CODE>catgets</CODE></A></H3>
<P>
There have been a few discussions of late on the use of
</P>
-<H3><A NAME="SEC196" HREF="gettext_toc.html#TOC196">11.6.3 Temporary - Why a single implementation</A></H3>
+<H3><A NAME="SEC198" HREF="gettext_toc.html#TOC198">11.6.3 Temporary - Why a single implementation</A></H3>
<P>
Now it seems kind of wasteful to me to have two different systems
</P>
-<H3><A NAME="SEC197" HREF="gettext_toc.html#TOC197">11.6.4 Temporary - Notes</A></H3>
+<H3><A NAME="SEC199" HREF="gettext_toc.html#TOC199">11.6.4 Temporary - Notes</A></H3>
<P>
X/Open agreed very late on the standard form so that many
projects / platform / upstream / gettext.git / blobdiff