release/src/router/gettext/gettext-tools/doc/gettext_10.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.52a
   4      from gettext.texi on 23 May 2005 -->
   5
   6 <TITLE>GNU gettext utilities - 10  The Programmer's View</TITLE>
   7 </HEAD>
   8 <BODY>
   9 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>.
  10 <P><HR><P>
  11
  12
  13 <H1><A NAME="SEC160" HREF="gettext_toc.html#TOC160">10  The Programmer's View</A></H1>
  14
  15 <P>
  16 One aim of the current message catalog implementation provided by
  17 GNU <CODE>gettext</CODE> was to use the system's message catalog handling, if the
  18 installer wishes to do so.  So we perhaps should first take a look at
  19 the solutions we know about.  The people in the POSIX committee did not
  20 manage to agree on one of the semi-official standards which we'll
  21 describe below.  In fact they couldn't agree on anything, so they decided
  22 only to include an example of an interface.  The major Unix vendors
  23 are split in the usage of the two most important specifications: X/Open's
  24 catgets vs. Uniforum's gettext interface.  We'll describe them both and
  25 later explain our solution of this dilemma.
  26
  27 </P>
  28
  29
  30
  31 <H2><A NAME="SEC161" HREF="gettext_toc.html#TOC161">10.1  About <CODE>catgets</CODE></A></H2>
  32 <P>
  33 <A NAME="IDX980"></A>
  34
  35 </P>
  36 <P>
  37 The <CODE>catgets</CODE> implementation is defined in the X/Open Portability
  38 Guide, Volume 3, XSI Supplementary Definitions, Chapter 5.  But the
  39 process of creating this standard seemed to be too slow for some of
  40 the Unix vendors so they created their implementations on preliminary
  41 versions of the standard.  Of course this leads again to problems while
  42 writing platform independent programs: even the usage of <CODE>catgets</CODE>
  43 does not guarantee a unique interface.
  44
  45 </P>
  46 <P>
  47 Another, personal comment on this that only a bunch of committee members
  48 could have made this interface.  They never really tried to program
  49 using this interface.  It is a fast, memory-saving implementation, an
  50 user can happily live with it.  But programmers hate it (at least I and
  51 some others do...)
  52
  53 </P>
  54 <P>
  55 But we must not forget one point: after all the trouble with transfering
  56 the rights on Unix(tm) they at last came to X/Open, the very same who
  57 published this specification.  This leads me to making the prediction
  58 that this interface will be in future Unix standards (e.g. Spec1170) and
  59 therefore part of all Unix implementation (implementations, which are
  60 <EM>allowed</EM> to wear this name).
  61
  62 </P>
  63
  64
  65
  66 <H3><A NAME="SEC162" HREF="gettext_toc.html#TOC162">10.1.1  The Interface</A></H3>
  67 <P>
  68 <A NAME="IDX981"></A>
  69
  70 </P>
  71 <P>
  72 The interface to the <CODE>catgets</CODE> implementation consists of three
  73 functions which correspond to those used in file access: <CODE>catopen</CODE>
  74 to open the catalog for using, <CODE>catgets</CODE> for accessing the message
  75 tables, and <CODE>catclose</CODE> for closing after work is done.  Prototypes
  76 for the functions and the needed definitions are in the
  77 <CODE>&#60;nl_types.h&#62;</CODE> header file.
  78
  79 </P>
  80 <P>
  81 <A NAME="IDX982"></A>
  82 <CODE>catopen</CODE> is used like in this:
  83
  84 </P>
  85
  86 <PRE>
  87 nl_catd catd = catopen ("catalog_name", 0);
  88 </PRE>
  89
  90 <P>
  91 The function takes as the argument the name of the catalog.  This usual
  92 refers to the name of the program or the package.  The second parameter
  93 is not further specified in the standard.  I don't even know whether it
  94 is implemented consistently among various systems.  So the common advice
  95 is to use <CODE>0</CODE> as the value.  The return value is a handle to the
  96 message catalog, equivalent to handles to file returned by <CODE>open</CODE>.
  97
  98 </P>
  99 <P>
 100 <A NAME="IDX983"></A>
 101 This handle is of course used in the <CODE>catgets</CODE> function which can
 102 be used like this:
 103
 104 </P>
 105
 106 <PRE>
 107 char *translation = catgets (catd, set_no, msg_id, "original string");
 108 </PRE>
 109
 110 <P>
 111 The first parameter is this catalog descriptor.  The second parameter
 112 specifies the set of messages in this catalog, in which the message
 113 described by <CODE>msg_id</CODE> is obtained.  <CODE>catgets</CODE> therefore uses a
 114 three-stage addressing:
 115
 116 </P>
 117
 118 <PRE>
 119 catalog name => set number => message ID => translation
 120 </PRE>
 121
 122 <P>
 123 The fourth argument is not used to address the translation.  It is given
 124 as a default value in case when one of the addressing stages fail.  One
 125 important thing to remember is that although the return type of catgets
 126 is <CODE>char *</CODE> the resulting string <EM>must not</EM> be changed.  It
 127 should better be <CODE>const char *</CODE>, but the standard is published in
 128 1988, one year before ANSI C.
 129
 130 </P>
 131 <P>
 132 <A NAME="IDX984"></A>
 133 The last of these functions is used and behaves as expected:
 134
 135 </P>
 136
 137 <PRE>
 138 catclose (catd);
 139 </PRE>
 140
 141 <P>
 142 After this no <CODE>catgets</CODE> call using the descriptor is legal anymore.
 143
 144 </P>
 145
 146
 147 <H3><A NAME="SEC163" HREF="gettext_toc.html#TOC163">10.1.2  Problems with the <CODE>catgets</CODE> Interface?!</A></H3>
 148 <P>
 149 <A NAME="IDX985"></A>
 150
 151 </P>
 152 <P>
 153 Now that this description seemed to be really easy -- where are the
 154 problems we speak of?  In fact the interface could be used in a
 155 reasonable way, but constructing the message catalogs is a pain.  The
 156 reason for this lies in the third argument of <CODE>catgets</CODE>: the unique
 157 message ID.  This has to be a numeric value for all messages in a single
 158 set.  Perhaps you could imagine the problems keeping such a list while
 159 changing the source code.  Add a new message here, remove one there.  Of
 160 course there have been developed a lot of tools helping to organize this
 161 chaos but one as the other fails in one aspect or the other.  We don't
 162 want to say that the other approach has no problems but they are far
 163 more easy to manage.
 164
 165 </P>
 166
 167
 168 <H2><A NAME="SEC164" HREF="gettext_toc.html#TOC164">10.2  About <CODE>gettext</CODE></A></H2>
 169 <P>
 170 <A NAME="IDX986"></A>
 171
 172 </P>
 173 <P>
 174 The definition of the <CODE>gettext</CODE> interface comes from a Uniforum
 175 proposal.  It was submitted there by Sun, who had implemented the
 176 <CODE>gettext</CODE> function in SunOS 4, around 1990.  Nowadays, the
 177 <CODE>gettext</CODE> interface is specified by the OpenI18N standard.
 178
 179 </P>
 180 <P>
 181 The main point about this solution is that it does not follow the
 182 method of normal file handling (open-use-close) and that it does not
 183 burden the programmer with so many tasks, especially the unique key handling.
 184 Of course here also a unique key is needed, but this key is the message
 185 itself (how long or short it is).  See section <A HREF="gettext_10.html#SEC172">10.3  Comparing the Two Interfaces</A> for a more
 186 detailed comparison of the two methods.
 187
 188 </P>
 189 <P>
 190 The following section contains a rather detailed description of the
 191 interface.  We make it that detailed because this is the interface
 192 we chose for the GNU <CODE>gettext</CODE> Library.  Programmers interested
 193 in using this library will be interested in this description.
 194
 195 </P>
 196
 197
 198
 199 <H3><A NAME="SEC165" HREF="gettext_toc.html#TOC165">10.2.1  The Interface</A></H3>
 200 <P>
 201 <A NAME="IDX987"></A>
 202
 203 </P>
 204 <P>
 205 The minimal functionality an interface must have is a) to select a
 206 domain the strings are coming from (a single domain for all programs is
 207 not reasonable because its construction and maintenance is difficult,
 208 perhaps impossible) and b) to access a string in a selected domain.
 209
 210 </P>
 211 <P>
 212 This is principally the description of the <CODE>gettext</CODE> interface.  It
 213 has a global domain which unqualified usages reference.  Of course this
 214 domain is selectable by the user.
 215
 216 </P>
 217
 218 <PRE>
 219 char *textdomain (const char *domain_name);
 220 </PRE>
 221
 222 <P>
 223 This provides the possibility to change or query the current status of
 224 the current global domain of the <CODE>LC_MESSAGE</CODE> category.  The
 225 argument is a null-terminated string, whose characters must be legal in
 226 the use in filenames.  If the <VAR>domain_name</VAR> argument is <CODE>NULL</CODE>,
 227 the function returns the current value.  If no value has been set
 228 before, the name of the default domain is returned: <EM>messages</EM>.
 229 Please note that although the return value of <CODE>textdomain</CODE> is of
 230 type <CODE>char *</CODE> no changing is allowed.  It is also important to know
 231 that no checks of the availability are made.  If the name is not
 232 available you will see this by the fact that no translations are provided.
 233
 234 </P>
 235 <P>
 236 To use a domain set by <CODE>textdomain</CODE> the function
 237
 238 </P>
 239
 240 <PRE>
 241 char *gettext (const char *msgid);
 242 </PRE>
 243
 244 <P>
 245 is to be used.  This is the simplest reasonable form one can imagine.
 246 The translation of the string <VAR>msgid</VAR> is returned if it is available
 247 in the current domain.  If it is not available, the argument itself is
 248 returned.  If the argument is <CODE>NULL</CODE> the result is undefined.
 249
 250 </P>
 251 <P>
 252 One thing which should come into mind is that no explicit dependency to
 253 the used domain is given.  The current value of the domain for the
 254 <CODE>LC_MESSAGES</CODE> locale is used.  If this changes between two
 255 executions of the same <CODE>gettext</CODE> call in the program, both calls
 256 reference a different message catalog.
 257
 258 </P>
 259 <P>
 260 For the easiest case, which is normally used in internationalized
 261 packages, once at the beginning of execution a call to <CODE>textdomain</CODE>
 262 is issued, setting the domain to a unique name, normally the package
 263 name.  In the following code all strings which have to be translated are
 264 filtered through the gettext function.  That's all, the package speaks
 265 your language.
 266
 267 </P>
 268
 269
 270 <H3><A NAME="SEC166" HREF="gettext_toc.html#TOC166">10.2.2  Solving Ambiguities</A></H3>
 271 <P>
 272 <A NAME="IDX988"></A>
 273 <A NAME="IDX989"></A>
 274 <A NAME="IDX990"></A>
 275
 276 </P>
 277 <P>
 278 While this single name domain works well for most applications there
 279 might be the need to get translations from more than one domain.  Of
 280 course one could switch between different domains with calls to
 281 <CODE>textdomain</CODE>, but this is really not convenient nor is it fast.  A
 282 possible situation could be one case subject to discussion during this
 283 writing:  all
 284 error messages of functions in the set of common used functions should
 285 go into a separate domain <CODE>error</CODE>.  By this mean we would only need
 286 to translate them once.
 287 Another case are messages from a library, as these <EM>have</EM> to be
 288 independent of the current domain set by the application.
 289
 290 </P>
 291 <P>
 292 For this reasons there are two more functions to retrieve strings:
 293
 294 </P>
 295
 296 <PRE>
 297 char *dgettext (const char *domain_name, const char *msgid);
 298 char *dcgettext (const char *domain_name, const char *msgid,
 299                  int category);
 300 </PRE>
 301
 302 <P>
 303 Both take an additional argument at the first place, which corresponds
 304 to the argument of <CODE>textdomain</CODE>.  The third argument of
 305 <CODE>dcgettext</CODE> allows to use another locale but <CODE>LC_MESSAGES</CODE>.
 306 But I really don't know where this can be useful.  If the
 307 <VAR>domain_name</VAR> is <CODE>NULL</CODE> or <VAR>category</VAR> has an value beside
 308 the known ones, the result is undefined.  It should also be noted that
 309 this function is not part of the second known implementation of this
 310 function family, the one found in Solaris.
 311
 312 </P>
 313 <P>
 314 A second ambiguity can arise by the fact, that perhaps more than one
 315 domain has the same name.  This can be solved by specifying where the
 316 needed message catalog files can be found.
 317
 318 </P>
 319
 320 <PRE>
 321 char *bindtextdomain (const char *domain_name,
 322                       const char *dir_name);
 323 </PRE>
 324
 325 <P>
 326 Calling this function binds the given domain to a file in the specified
 327 directory (how this file is determined follows below).  Especially a
 328 file in the systems default place is not favored against the specified
 329 file anymore (as it would be by solely using <CODE>textdomain</CODE>).  A
 330 <CODE>NULL</CODE> pointer for the <VAR>dir_name</VAR> parameter returns the binding
 331 associated with <VAR>domain_name</VAR>.  If <VAR>domain_name</VAR> itself is
 332 <CODE>NULL</CODE> nothing happens and a <CODE>NULL</CODE> pointer is returned.  Here
 333 again as for all the other functions is true that none of the return
 334 value must be changed!
 335
 336 </P>
 337 <P>
 338 It is important to remember that relative path names for the
 339 <VAR>dir_name</VAR> parameter can be trouble.  Since the path is always
 340 computed relative to the current directory different results will be
 341 achieved when the program executes a <CODE>chdir</CODE> command.  Relative
 342 paths should always be avoided to avoid dependencies and
 343 unreliabilities.
 344
 345 </P>
 346
 347
 348 <H3><A NAME="SEC167" HREF="gettext_toc.html#TOC167">10.2.3  Locating Message Catalog Files</A></H3>
 349 <P>
 350 <A NAME="IDX991"></A>
 351
 352 </P>
 353 <P>
 354 Because many different languages for many different packages have to be
 355 stored we need some way to add these information to file message catalog
 356 files.  The way usually used in Unix environments is have this encoding
 357 in the file name.  This is also done here.  The directory name given in
 358 <CODE>bindtextdomain</CODE>s second argument (or the default directory),
 359 followed by the value and name of the locale and the domain name are
 360 concatenated:
 361
 362 </P>
 363
 364 <PRE>
 365 <VAR>dir_name</VAR>/<VAR>locale</VAR>/LC_<VAR>category</VAR>/<VAR>domain_name</VAR>.mo
 366 </PRE>
 367
 368 <P>
 369 The default value for <VAR>dir_name</VAR> is system specific.  For the GNU
 370 library, and for packages adhering to its conventions, it's:
 371
 372 <PRE>
 373 /usr/local/share/locale
 374 </PRE>
 375
 376 <P>
 377 <VAR>locale</VAR> is the value of the locale whose name is this
 378 <CODE>LC_<VAR>category</VAR></CODE>.  For <CODE>gettext</CODE> and <CODE>dgettext</CODE> this
 379 <CODE>LC_<VAR>category</VAR></CODE> is always <CODE>LC_MESSAGES</CODE>.<A NAME="DOCF3" HREF="gettext_foot.html#FOOT3">(3)</A>
 380 The value of the locale is determined through
 381 <CODE>setlocale (LC_<VAR>category</VAR>, NULL)</CODE>.
 382 <A NAME="DOCF4" HREF="gettext_foot.html#FOOT4">(4)</A>
 383 <CODE>dcgettext</CODE> specifies the locale category by the third argument.
 384
 385 </P>
 386
 387
 388 <H3><A NAME="SEC168" HREF="gettext_toc.html#TOC168">10.2.4  How to specify the output character set <CODE>gettext</CODE> uses</A></H3>
 389 <P>
 390 <A NAME="IDX992"></A>
 391 <A NAME="IDX993"></A>
 392
 393 </P>
 394 <P>
 395 <CODE>gettext</CODE> not only looks up a translation in a message catalog.  It
 396 also converts the translation on the fly to the desired output character
 397 set.  This is useful if the user is working in a different character set
 398 than the translator who created the message catalog, because it avoids
 399 distributing variants of message catalogs which differ only in the
 400 character set.
 401
 402 </P>
 403 <P>
 404 The output character set is, by default, the value of <CODE>nl_langinfo
 405 (CODESET)</CODE>, which depends on the <CODE>LC_CTYPE</CODE> part of the current
 406 locale.  But programs which store strings in a locale independent way
 407 (e.g. UTF-8) can request that <CODE>gettext</CODE> and related functions
 408 return the translations in that encoding, by use of the
 409 <CODE>bind_textdomain_codeset</CODE> function.
 410
 411 </P>
 412 <P>
 413 Note that the <VAR>msgid</VAR> argument to <CODE>gettext</CODE> is not subject to
 414 character set conversion.  Also, when <CODE>gettext</CODE> does not find a
 415 translation for <VAR>msgid</VAR>, it returns <VAR>msgid</VAR> unchanged --
 416 independently of the current output character set.  It is therefore
 417 recommended that all <VAR>msgid</VAR>s be US-ASCII strings.
 418
 419 </P>
 420 <P>
 421 <DL>
 422 <DT><U>Function:</U> char * <B>bind_textdomain_codeset</B> <I>(const char *<VAR>domainname</VAR>, const char *<VAR>codeset</VAR>)</I>
 423 <DD><A NAME="IDX994"></A>
 424 The <CODE>bind_textdomain_codeset</CODE> function can be used to specify the
 425 output character set for message catalogs for domain <VAR>domainname</VAR>.
 426 The <VAR>codeset</VAR> argument must be a valid codeset name which can be used
 427 for the <CODE>iconv_open</CODE> function, or a null pointer.
 428
 429 </P>
 430 <P>
 431 If the <VAR>codeset</VAR> parameter is the null pointer,
 432 <CODE>bind_textdomain_codeset</CODE> returns the currently selected codeset
 433 for the domain with the name <VAR>domainname</VAR>.  It returns <CODE>NULL</CODE> if
 434 no codeset has yet been selected.
 435
 436 </P>
 437 <P>
 438 The <CODE>bind_textdomain_codeset</CODE> function can be used several times.
 439 If used multiple times with the same <VAR>domainname</VAR> argument, the
 440 later call overrides the settings made by the earlier one.
 441
 442 </P>
 443 <P>
 444 The <CODE>bind_textdomain_codeset</CODE> function returns a pointer to a
 445 string containing the name of the selected codeset.  The string is
 446 allocated internally in the function and must not be changed by the
 447 user.  If the system went out of core during the execution of
 448 <CODE>bind_textdomain_codeset</CODE>, the return value is <CODE>NULL</CODE> and the
 449 global variable <VAR>errno</VAR> is set accordingly.
 450 </DL>
 451
 452 </P>
 453
 454
 455 <H3><A NAME="SEC169" HREF="gettext_toc.html#TOC169">10.2.5  Additional functions for plural forms</A></H3>
 456 <P>
 457 <A NAME="IDX995"></A>
 458
 459 </P>
 460 <P>
 461 The functions of the <CODE>gettext</CODE> family described so far (and all the
 462 <CODE>catgets</CODE> functions as well) have one problem in the real world
 463 which have been neglected completely in all existing approaches.  What
 464 is meant here is the handling of plural forms.
 465
 466 </P>
 467 <P>
 468 Looking through Unix source code before the time anybody thought about
 469 internationalization (and, sadly, even afterwards) one can often find
 470 code similar to the following:
 471
 472 </P>
 473
 474 <PRE>
 475    printf ("%d file%s deleted", n, n == 1 ? "" : "s");
 476 </PRE>
 477
 478 <P>
 479 After the first complaints from people internationalizing the code people
 480 either completely avoided formulations like this or used strings like
 481 <CODE>"file(s)"</CODE>.  Both look unnatural and should be avoided.  First
 482 tries to solve the problem correctly looked like this:
 483
 484 </P>
 485
 486 <PRE>
 487    if (n == 1)
 488      printf ("%d file deleted", n);
 489    else
 490      printf ("%d files deleted", n);
 491 </PRE>
 492
 493 <P>
 494 But this does not solve the problem.  It helps languages where the
 495 plural form of a noun is not simply constructed by adding an `s' but
 496 that is all.  Once again people fell into the trap of believing the
 497 rules their language is using are universal.  But the handling of plural
 498 forms differs widely between the language families.  For example,
 499 Rafal Maszkowski <CODE>&#60;rzm@mat.uni.torun.pl&#62;</CODE> reports:
 500
 501 </P>
 502
 503 <BLOCKQUOTE>
 504 <P>
 505 In Polish we use e.g. plik (file) this way:
 506
 507 <PRE>
 508 1 plik
 509 2,3,4 pliki
 510 5-21 pliko'w
 511 22-24 pliki
 512 25-31 pliko'w
 513 </PRE>
 514
 515 <P>
 516 and so on (o' means 8859-2 oacute which should be rather okreska,
 517 similar to aogonek).
 518 </BLOCKQUOTE>
 519
 520 <P>
 521 There are two things which can differ between languages (and even inside
 522 language families);
 523
 524 </P>
 525
 526 <UL>
 527 <LI>
 528
 529 The form how plural forms are built differs.  This is a problem with
 530 languages which have many irregularities.  German, for instance, is a
 531 drastic case.  Though English and German are part of the same language
 532 family (Germanic), the almost regular forming of plural noun forms
 533 (appending an `s') is hardly found in German.
 534
 535 <LI>
 536
 537 The number of plural forms differ.  This is somewhat surprising for
 538 those who only have experiences with Romanic and Germanic languages
 539 since here the number is the same (there are two).
 540
 541 But other language families have only one form or many forms.  More
 542 information on this in an extra section.
 543 </UL>
 544
 545 <P>
 546 The consequence of this is that application writers should not try to
 547 solve the problem in their code.  This would be localization since it is
 548 only usable for certain, hardcoded language environments.  Instead the
 549 extended <CODE>gettext</CODE> interface should be used.
 550
 551 </P>
 552 <P>
 553 These extra functions are taking instead of the one key string two
 554 strings and a numerical argument.  The idea behind this is that using
 555 the numerical argument and the first string as a key, the implementation
 556 can select using rules specified by the translator the right plural
 557 form.  The two string arguments then will be used to provide a return
 558 value in case no message catalog is found (similar to the normal
 559 <CODE>gettext</CODE> behavior).  In this case the rules for Germanic language
 560 is used and it is assumed that the first string argument is the singular
 561 form, the second the plural form.
 562
 563 </P>
 564 <P>
 565 This has the consequence that programs without language catalogs can
 566 display the correct strings only if the program itself is written using
 567 a Germanic language.  This is a limitation but since the GNU C library
 568 (as well as the GNU <CODE>gettext</CODE> package) are written as part of the
 569 GNU package and the coding standards for the GNU project require program
 570 being written in English, this solution nevertheless fulfills its
 571 purpose.
 572
 573 </P>
 574 <P>
 575 <DL>
 576 <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>
 577 <DD><A NAME="IDX996"></A>
 578 The <CODE>ngettext</CODE> function is similar to the <CODE>gettext</CODE> function
 579 as it finds the message catalogs in the same way.  But it takes two
 580 extra arguments.  The <VAR>msgid1</VAR> parameter must contain the singular
 581 form of the string to be converted.  It is also used as the key for the
 582 search in the catalog.  The <VAR>msgid2</VAR> parameter is the plural form.
 583 The parameter <VAR>n</VAR> is used to determine the plural form.  If no
 584 message catalog is found <VAR>msgid1</VAR> is returned if <CODE>n == 1</CODE>,
 585 otherwise <CODE>msgid2</CODE>.
 586
 587 </P>
 588 <P>
 589 An example for the use of this function is:
 590
 591 </P>
 592
 593 <PRE>
 594 printf (ngettext ("%d file removed", "%d files removed", n), n);
 595 </PRE>
 596
 597 <P>
 598 Please note that the numeric value <VAR>n</VAR> has to be passed to the
 599 <CODE>printf</CODE> function as well.  It is not sufficient to pass it only to
 600 <CODE>ngettext</CODE>.
 601 </DL>
 602
 603 </P>
 604 <P>
 605 <DL>
 606 <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>
 607 <DD><A NAME="IDX997"></A>
 608 The <CODE>dngettext</CODE> is similar to the <CODE>dgettext</CODE> function in the
 609 way the message catalog is selected.  The difference is that it takes
 610 two extra parameter to provide the correct plural form.  These two
 611 parameters are handled in the same way <CODE>ngettext</CODE> handles them.
 612 </DL>
 613
 614 </P>
 615 <P>
 616 <DL>
 617 <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>
 618 <DD><A NAME="IDX998"></A>
 619 The <CODE>dcngettext</CODE> is similar to the <CODE>dcgettext</CODE> function in the
 620 way the message catalog is selected.  The difference is that it takes
 621 two extra parameter to provide the correct plural form.  These two
 622 parameters are handled in the same way <CODE>ngettext</CODE> handles them.
 623 </DL>
 624
 625 </P>
 626 <P>
 627 Now, how do these functions solve the problem of the plural forms?
 628 Without the input of linguists (which was not available) it was not
 629 possible to determine whether there are only a few different forms in
 630 which plural forms are formed or whether the number can increase with
 631 every new supported language.
 632
 633 </P>
 634 <P>
 635 Therefore the solution implemented is to allow the translator to specify
 636 the rules of how to select the plural form.  Since the formula varies
 637 with every language this is the only viable solution except for
 638 hardcoding the information in the code (which still would require the
 639 possibility of extensions to not prevent the use of new languages).
 640
 641 </P>
 642 <P>
 643 <A NAME="IDX999"></A>
 644 <A NAME="IDX1000"></A>
 645 <A NAME="IDX1001"></A>
 646 The information about the plural form selection has to be stored in the
 647 header entry of the PO file (the one with the empty <CODE>msgid</CODE> string).
 648 The plural form information looks like this:
 649
 650 </P>
 651
 652 <PRE>
 653 Plural-Forms: nplurals=2; plural=n == 1 ? 0 : 1;
 654 </PRE>
 655
 656 <P>
 657 The <CODE>nplurals</CODE> value must be a decimal number which specifies how
 658 many different plural forms exist for this language.  The string
 659 following <CODE>plural</CODE> is an expression which is using the C language
 660 syntax.  Exceptions are that no negative numbers are allowed, numbers
 661 must be decimal, and the only variable allowed is <CODE>n</CODE>.  This
 662 expression will be evaluated whenever one of the functions
 663 <CODE>ngettext</CODE>, <CODE>dngettext</CODE>, or <CODE>dcngettext</CODE> is called.  The
 664 numeric value passed to these functions is then substituted for all uses
 665 of the variable <CODE>n</CODE> in the expression.  The resulting value then
 666 must be greater or equal to zero and smaller than the value given as the
 667 value of <CODE>nplurals</CODE>.
 668
 669 </P>
 670 <P>
 671 <A NAME="IDX1002"></A>
 672 The following rules are known at this point.  The language with families
 673 are listed.  But this does not necessarily mean the information can be
 674 generalized for the whole family (as can be easily seen in the table
 675 below).<A NAME="DOCF5" HREF="gettext_foot.html#FOOT5">(5)</A>
 676
 677 </P>
 678 <DL COMPACT>
 679
 680 <DT>Only one form:
 681 <DD>
 682 Some languages only require one single form.  There is no distinction
 683 between the singular and plural form.  An appropriate header entry
 684 would look like this:
 685
 686
 687 <PRE>
 688 Plural-Forms: nplurals=1; plural=0;
 689 </PRE>
 690
 691 Languages with this property include:
 692
 693 <DL COMPACT>
 694
 695 <DT>Finno-Ugric family
 696 <DD>
 697 Hungarian
 698 <DT>Asian family
 699 <DD>
 700 Japanese, Korean, Vietnamese
 701 <DT>Turkic/Altaic family
 702 <DD>
 703 Turkish
 704 </DL>
 705
 706 <DT>Two forms, singular used for one only
 707 <DD>
 708 This is the form used in most existing programs since it is what English
 709 is using.  A header entry would look like this:
 710
 711
 712 <PRE>
 713 Plural-Forms: nplurals=2; plural=n != 1;
 714 </PRE>
 715
 716 (Note: this uses the feature of C expressions that boolean expressions
 717 have to value zero or one.)
 718
 719 Languages with this property include:
 720
 721 <DL COMPACT>
 722
 723 <DT>Germanic family
 724 <DD>
 725 Danish, Dutch, English, Faroese, German, Norwegian, Swedish
 726 <DT>Finno-Ugric family
 727 <DD>
 728 Estonian, Finnish
 729 <DT>Latin/Greek family
 730 <DD>
 731 Greek
 732 <DT>Semitic family
 733 <DD>
 734 Hebrew
 735 <DT>Romanic family
 736 <DD>
 737 Italian, Portuguese, Spanish
 738 <DT>Artificial
 739 <DD>
 740 Esperanto
 741 </DL>
 742
 743 <DT>Two forms, singular used for zero and one
 744 <DD>
 745 Exceptional case in the language family.  The header entry would be:
 746
 747
 748 <PRE>
 749 Plural-Forms: nplurals=2; plural=n&#62;1;
 750 </PRE>
 751
 752 Languages with this property include:
 753
 754 <DL COMPACT>
 755
 756 <DT>Romanic family
 757 <DD>
 758 French, Brazilian Portuguese
 759 </DL>
 760
 761 <DT>Three forms, special case for zero
 762 <DD>
 763 The header entry would be:
 764
 765
 766 <PRE>
 767 Plural-Forms: nplurals=3; plural=n%10==1 &#38;&#38; n%100!=11 ? 0 : n != 0 ? 1 : 2;
 768 </PRE>
 769
 770 Languages with this property include:
 771
 772 <DL COMPACT>
 773
 774 <DT>Baltic family
 775 <DD>
 776 Latvian
 777 </DL>
 778
 779 <DT>Three forms, special cases for one and two
 780 <DD>
 781 The header entry would be:
 782
 783
 784 <PRE>
 785 Plural-Forms: nplurals=3; plural=n==1 ? 0 : n==2 ? 1 : 2;
 786 </PRE>
 787
 788 Languages with this property include:
 789
 790 <DL COMPACT>
 791
 792 <DT>Celtic
 793 <DD>
 794 Gaeilge (Irish)
 795 </DL>
 796
 797 <DT>Three forms, special case for numbers ending in 1[2-9]
 798 <DD>
 799 The header entry would look like this:
 800
 801
 802 <PRE>
 803 Plural-Forms: nplurals=3; \
 804     plural=n%10==1 &#38;&#38; n%100!=11 ? 0 : \
 805            n%10&#62;=2 &#38;&#38; (n%100&#60;10 || n%100&#62;=20) ? 1 : 2;
 806 </PRE>
 807
 808 Languages with this property include:
 809
 810 <DL COMPACT>
 811
 812 <DT>Baltic family
 813 <DD>
 814 Lithuanian
 815 </DL>
 816
 817 <DT>Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
 818 <DD>
 819 The header entry would look like this:
 820
 821
 822 <PRE>
 823 Plural-Forms: nplurals=3; \
 824     plural=n%10==1 &#38;&#38; n%100!=11 ? 0 : \
 825            n%10&#62;=2 &#38;&#38; n%10&#60;=4 &#38;&#38; (n%100&#60;10 || n%100&#62;=20) ? 1 : 2;
 826 </PRE>
 827
 828 Languages with this property include:
 829
 830 <DL COMPACT>
 831
 832 <DT>Slavic family
 833 <DD>
 834 Croatian, Serbian, Russian, Ukrainian
 835 </DL>
 836
 837 <DT>Three forms, special cases for 1 and 2, 3, 4
 838 <DD>
 839 The header entry would look like this:
 840
 841
 842 <PRE>
 843 Plural-Forms: nplurals=3; \
 844     plural=(n==1) ? 0 : (n&#62;=2 &#38;&#38; n&#60;=4) ? 1 : 2;
 845 </PRE>
 846
 847 Languages with this property include:
 848
 849 <DL COMPACT>
 850
 851 <DT>Slavic family
 852 <DD>
 853 Slovak, Czech
 854 </DL>
 855
 856 <DT>Three forms, special case for one and some numbers ending in 2, 3, or 4
 857 <DD>
 858 The header entry would look like this:
 859
 860
 861 <PRE>
 862 Plural-Forms: nplurals=3; \
 863     plural=n==1 ? 0 : \
 864            n%10&#62;=2 &#38;&#38; n%10&#60;=4 &#38;&#38; (n%100&#60;10 || n%100&#62;=20) ? 1 : 2;
 865 </PRE>
 866
 867 Languages with this property include:
 868
 869 <DL COMPACT>
 870
 871 <DT>Slavic family
 872 <DD>
 873 Polish
 874 </DL>
 875
 876 <DT>Four forms, special case for one and all numbers ending in 02, 03, or 04
 877 <DD>
 878 The header entry would look like this:
 879
 880
 881 <PRE>
 882 Plural-Forms: nplurals=4; \
 883     plural=n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
 884 </PRE>
 885
 886 Languages with this property include:
 887
 888 <DL COMPACT>
 889
 890 <DT>Slavic family
 891 <DD>
 892 Slovenian
 893 </DL>
 894 </DL>
 895
 896
 897
 898 <H3><A NAME="SEC170" HREF="gettext_toc.html#TOC170">10.2.6  How to use <CODE>gettext</CODE> in GUI programs</A></H3>
 899 <P>
 900 <A NAME="IDX1003"></A>
 901 <A NAME="IDX1004"></A>
 902 <A NAME="IDX1005"></A>
 903
 904 </P>
 905 <P>
 906 One place where the <CODE>gettext</CODE> functions, if used normally, have big
 907 problems is within programs with graphical user interfaces (GUIs).  The
 908 problem is that many of the strings which have to be translated are very
 909 short.  They have to appear in pull-down menus which restricts the
 910 length.  But strings which are not containing entire sentences or at
 911 least large fragments of a sentence may appear in more than one
 912 situation in the program but might have different translations.  This is
 913 especially true for the one-word strings which are frequently used in
 914 GUI programs.
 915
 916 </P>
 917 <P>
 918 As a consequence many people say that the <CODE>gettext</CODE> approach is
 919 wrong and instead <CODE>catgets</CODE> should be used which indeed does not
 920 have this problem.  But there is a very simple and powerful method to
 921 handle these kind of problems with the <CODE>gettext</CODE> functions.
 922
 923 </P>
 924 <P>
 925 As as example consider the following fictional situation.  A GUI program
 926 has a menu bar with the following entries:
 927
 928 </P>
 929
 930 <PRE>
 931 +------------+------------+--------------------------------------+
 932 | File       | Printer    |                                      |
 933 +------------+------------+--------------------------------------+
 934 | Open     | | Select   |
 935 | New      | | Open     |
 936 +----------+ | Connect  |
 937              +----------+
 938 </PRE>
 939
 940 <P>
 941 To have the strings <CODE>File</CODE>, <CODE>Printer</CODE>, <CODE>Open</CODE>,
 942 <CODE>New</CODE>, <CODE>Select</CODE>, and <CODE>Connect</CODE> translated there has to be
 943 at some point in the code a call to a function of the <CODE>gettext</CODE>
 944 family.  But in two places the string passed into the function would be
 945 <CODE>Open</CODE>.  The translations might not be the same and therefore we
 946 are in the dilemma described above.
 947
 948 </P>
 949 <P>
 950 One solution to this problem is to artificially enlengthen the strings
 951 to make them unambiguous.  But what would the program do if no
 952 translation is available?  The enlengthened string is not what should be
 953 printed.  So we should use a little bit modified version of the functions.
 954
 955 </P>
 956 <P>
 957 To enlengthen the strings a uniform method should be used.  E.g., in the
 958 example above the strings could be chosen as
 959
 960 </P>
 961
 962 <PRE>
 963 Menu|File
 964 Menu|Printer
 965 Menu|File|Open
 966 Menu|File|New
 967 Menu|Printer|Select
 968 Menu|Printer|Open
 969 Menu|Printer|Connect
 970 </PRE>
 971
 972 <P>
 973 Now all the strings are different and if now instead of <CODE>gettext</CODE>
 974 the following little wrapper function is used, everything works just
 975 fine:
 976
 977 </P>
 978 <P>
 979 <A NAME="IDX1006"></A>
 980
 981 <PRE>
 982   char *
 983   sgettext (const char *msgid)
 984   {
 985     char *msgval = gettext (msgid);
 986     if (msgval == msgid)
 987       msgval = strrchr (msgid, '|') + 1;
 988     return msgval;
 989   }
 990 </PRE>
 991
 992 <P>
 993 What this little function does is to recognize the case when no
 994 translation is available.  This can be done very efficiently by a
 995 pointer comparison since the return value is the input value.  If there
 996 is no translation we know that the input string is in the format we used
 997 for the Menu entries and therefore contains a <CODE>|</CODE> character.  We
 998 simply search for the last occurrence of this character and return a
 999 pointer to the character following it.  That's it!
1000
1001 </P>
1002 <P>
1003 If one now consistently uses the enlengthened string form and replaces
1004 the <CODE>gettext</CODE> calls with calls to <CODE>sgettext</CODE> (this is normally
1005 limited to very few places in the GUI implementation) then it is
1006 possible to produce a program which can be internationalized.
1007
1008 </P>
1009 <P>
1010 The other <CODE>gettext</CODE> functions (<CODE>dgettext</CODE>, <CODE>dcgettext</CODE>
1011 and the <CODE>ngettext</CODE> equivalents) can and should have corresponding
1012 functions as well which look almost identical, except for the parameters
1013 and the call to the underlying function.
1014
1015 </P>
1016 <P>
1017 Now there is of course the question why such functions do not exist in
1018 the GNU gettext package?  There are two parts of the answer to this question.
1019
1020 </P>
1021
1022 <UL>
1023 <LI>
1024
1025 They are easy to write and therefore can be provided by the project they
1026 are used in.  This is not an answer by itself and must be seen together
1027 with the second part which is:
1028
1029 <LI>
1030
1031 There is no way the gettext package can contain a version which can work
1032 everywhere.  The problem is the selection of the character to separate
1033 the prefix from the actual string in the enlenghtened string.  The
1034 examples above used <CODE>|</CODE> which is a quite good choice because it
1035 resembles a notation frequently used in this context and it also is a
1036 character not often used in message strings.
1037
1038 But what if the character is used in message strings?  Or if the chose
1039 character is not available in the character set on the machine one
1040 compiles (e.g., <CODE>|</CODE> is not required to exist for ISO C; this is
1041 why the <TT>`iso646.h&acute;</TT> file exists in ISO C programming environments).
1042 </UL>
1043
1044 <P>
1045 There is only one more comment to be said.  The wrapper function above
1046 requires that the translations strings are not enlengthened themselves.
1047 This is only logical.  There is no need to disambiguate the strings
1048 (since they are never used as keys for a search) and one also saves
1049 quite some memory and disk space by doing this.
1050
1051 </P>
1052
1053
1054 <H3><A NAME="SEC171" HREF="gettext_toc.html#TOC171">10.2.7  Optimization of the *gettext functions</A></H3>
1055 <P>
1056 <A NAME="IDX1007"></A>
1057
1058 </P>
1059 <P>
1060 At this point of the discussion we should talk about an advantage of the
1061 GNU <CODE>gettext</CODE> implementation.  Some readers might have pointed out
1062 that an internationalized program might have a poor performance if some
1063 string has to be translated in an inner loop.  While this is unavoidable
1064 when the string varies from one run of the loop to the other it is
1065 simply a waste of time when the string is always the same.  Take the
1066 following example:
1067
1068 </P>
1069
1070 <PRE>
1071 {
1072   while (...)
1073     {
1074       puts (gettext ("Hello world"));
1075     }
1076 }
1077 </PRE>
1078
1079 <P>
1080 When the locale selection does not change between two runs the resulting
1081 string is always the same.  One way to use this is:
1082
1083 </P>
1084
1085 <PRE>
1086 {
1087   str = gettext ("Hello world");
1088   while (...)
1089     {
1090       puts (str);
1091     }
1092 }
1093 </PRE>
1094
1095 <P>
1096 But this solution is not usable in all situation (e.g. when the locale
1097 selection changes) nor does it lead to legible code.
1098
1099 </P>
1100 <P>
1101 For this reason, GNU <CODE>gettext</CODE> caches previous translation results.
1102 When the same translation is requested twice, with no new message
1103 catalogs being loaded in between, <CODE>gettext</CODE> will, the second time,
1104 find the result through a single cache lookup.
1105
1106 </P>
1107
1108
1109 <H2><A NAME="SEC172" HREF="gettext_toc.html#TOC172">10.3  Comparing the Two Interfaces</A></H2>
1110 <P>
1111 <A NAME="IDX1008"></A>
1112 <A NAME="IDX1009"></A>
1113
1114 </P>
1115
1116 <P>
1117 The following discussion is perhaps a little bit colored.  As said
1118 above we implemented GNU <CODE>gettext</CODE> following the Uniforum
1119 proposal and this surely has its reasons.  But it should show how we
1120 came to this decision.
1121
1122 </P>
1123 <P>
1124 First we take a look at the developing process.  When we write an
1125 application using NLS provided by <CODE>gettext</CODE> we proceed as always.
1126 Only when we come to a string which might be seen by the users and thus
1127 has to be translated we use <CODE>gettext("...")</CODE> instead of
1128 <CODE>"..."</CODE>.  At the beginning of each source file (or in a central
1129 header file) we define
1130
1131 </P>
1132
1133 <PRE>
1134 #define gettext(String) (String)
1135 </PRE>
1136
1137 <P>
1138 Even this definition can be avoided when the system supports the
1139 <CODE>gettext</CODE> function in its C library.  When we compile this code the
1140 result is the same as if no NLS code is used.  When  you take a look at
1141 the GNU <CODE>gettext</CODE> code you will see that we use <CODE>_("...")</CODE>
1142 instead of <CODE>gettext("...")</CODE>.  This reduces the number of
1143 additional characters per translatable string to <EM>3</EM> (in words:
1144 three).
1145
1146 </P>
1147 <P>
1148 When now a production version of the program is needed we simply replace
1149 the definition
1150
1151 </P>
1152
1153 <PRE>
1154 #define _(String) (String)
1155 </PRE>
1156
1157 <P>
1158 by
1159
1160 </P>
1161 <P>
1162 <A NAME="IDX1010"></A>
1163
1164 <PRE>
1165 #include &#60;libintl.h&#62;
1166 #define _(String) gettext (String)
1167 </PRE>
1168
1169 <P>
1170 Additionally we run the program <TT>`xgettext&acute;</TT> on all source code file
1171 which contain translatable strings and that's it: we have a running
1172 program which does not depend on translations to be available, but which
1173 can use any that becomes available.
1174
1175 </P>
1176 <P>
1177 <A NAME="IDX1011"></A>
1178 The same procedure can be done for the <CODE>gettext_noop</CODE> invocations
1179 (see section <A HREF="gettext_3.html#SEC19">3.6  Special Cases of Translatable Strings</A>).  One usually defines <CODE>gettext_noop</CODE> as a
1180 no-op macro.  So you should consider the following code for your project:
1181
1182 </P>
1183
1184 <PRE>
1185 #define gettext_noop(String) String
1186 #define N_(String) gettext_noop (String)
1187 </PRE>
1188
1189 <P>
1190 <CODE>N_</CODE> is a short form similar to <CODE>_</CODE>.  The <TT>`Makefile&acute;</TT> in
1191 the <TT>`po/&acute;</TT> directory of GNU <CODE>gettext</CODE> knows by default both of the
1192 mentioned short forms so you are invited to follow this proposal for
1193 your own ease.
1194
1195 </P>
1196 <P>
1197 Now to <CODE>catgets</CODE>.  The main problem is the work for the
1198 programmer.  Every time he comes to a translatable string he has to
1199 define a number (or a symbolic constant) which has also be defined in
1200 the message catalog file.  He also has to take care for duplicate
1201 entries, duplicate message IDs etc.  If he wants to have the same
1202 quality in the message catalog as the GNU <CODE>gettext</CODE> program
1203 provides he also has to put the descriptive comments for the strings and
1204 the location in all source code files in the message catalog.  This is
1205 nearly a Mission: Impossible.
1206
1207 </P>
1208 <P>
1209 But there are also some points people might call advantages speaking for
1210 <CODE>catgets</CODE>.  If you have a single word in a string and this string
1211 is used in different contexts it is likely that in one or the other
1212 language the word has different translations.  Example:
1213
1214 </P>
1215
1216 <PRE>
1217 printf ("%s: %d", gettext ("number"), number_of_errors)
1218
1219 printf ("you should see %d %s", number_count,
1220         number_count == 1 ? gettext ("number") : gettext ("numbers"))
1221 </PRE>
1222
1223 <P>
1224 Here we have to translate two times the string <CODE>"number"</CODE>.  Even
1225 if you do not speak a language beside English it might be possible to
1226 recognize that the two words have a different meaning.  In German the
1227 first appearance has to be translated to <CODE>"Anzahl"</CODE> and the second
1228 to <CODE>"Zahl"</CODE>.
1229
1230 </P>
1231 <P>
1232 Now you can say that this example is really esoteric.  And you are
1233 right!  This is exactly how we felt about this problem and decide that
1234 it does not weight that much.  The solution for the above problem could
1235 be very easy:
1236
1237 </P>
1238
1239 <PRE>
1240 printf ("%s %d", gettext ("number:"), number_of_errors)
1241
1242 printf (number_count == 1 ? gettext ("you should see %d number")
1243                           : gettext ("you should see %d numbers"),
1244         number_count)
1245 </PRE>
1246
1247 <P>
1248 We believe that we can solve all conflicts with this method.  If it is
1249 difficult one can also consider changing one of the conflicting string a
1250 little bit.  But it is not impossible to overcome.
1251
1252 </P>
1253 <P>
1254 <CODE>catgets</CODE> allows same original entry to have different translations,
1255 but <CODE>gettext</CODE> has another, scalable approach for solving ambiguities
1256 of this kind: See section <A HREF="gettext_10.html#SEC166">10.2.2  Solving Ambiguities</A>.
1257
1258 </P>
1259
1260
1261 <H2><A NAME="SEC173" HREF="gettext_toc.html#TOC173">10.4  Using libintl.a in own programs</A></H2>
1262
1263 <P>
1264 Starting with version 0.9.4 the library <CODE>libintl.h</CODE> should be
1265 self-contained.  I.e., you can use it in your own programs without
1266 providing additional functions.  The <TT>`Makefile&acute;</TT> will put the header
1267 and the library in directories selected using the <CODE>$(prefix)</CODE>.
1268
1269 </P>
1270
1271
1272 <H2><A NAME="SEC174" HREF="gettext_toc.html#TOC174">10.5  Being a <CODE>gettext</CODE> grok</A></H2>
1273
1274 <P>
1275 To fully exploit the functionality of the GNU <CODE>gettext</CODE> library it
1276 is surely helpful to read the source code.  But for those who don't want
1277 to spend that much time in reading the (sometimes complicated) code here
1278 is a list comments:
1279
1280 </P>
1281
1282 <UL>
1283 <LI>Changing the language at runtime
1284
1285 <A NAME="IDX1012"></A>
1286
1287 For interactive programs it might be useful to offer a selection of the
1288 used language at runtime.  To understand how to do this one need to know
1289 how the used language is determined while executing the <CODE>gettext</CODE>
1290 function.  The method which is presented here only works correctly
1291 with the GNU implementation of the <CODE>gettext</CODE> functions.
1292
1293 In the function <CODE>dcgettext</CODE> at every call the current setting of
1294 the highest priority environment variable is determined and used.
1295 Highest priority means here the following list with decreasing
1296 priority:
1297
1298
1299 <OL>
1300 <LI><CODE>LANGUAGE</CODE>
1301
1302 <A NAME="IDX1013"></A>
1303
1304 <A NAME="IDX1014"></A>
1305 <LI><CODE>LC_ALL</CODE>
1306
1307 <A NAME="IDX1015"></A>
1308 <A NAME="IDX1016"></A>
1309 <A NAME="IDX1017"></A>
1310 <A NAME="IDX1018"></A>
1311 <A NAME="IDX1019"></A>
1312 <A NAME="IDX1020"></A>
1313 <LI><CODE>LC_xxx</CODE>, according to selected locale
1314
1315 <A NAME="IDX1021"></A>
1316 <LI><CODE>LANG</CODE>
1317
1318 </OL>
1319
1320 Afterwards the path is constructed using the found value and the
1321 translation file is loaded if available.
1322
1323 What happens now when the value for, say, <CODE>LANGUAGE</CODE> changes?  According
1324 to the process explained above the new value of this variable is found
1325 as soon as the <CODE>dcgettext</CODE> function is called.  But this also means
1326 the (perhaps) different message catalog file is loaded.  In other
1327 words: the used language is changed.
1328
1329 But there is one little hook.  The code for gcc-2.7.0 and up provides
1330 some optimization.  This optimization normally prevents the calling of
1331 the <CODE>dcgettext</CODE> function as long as no new catalog is loaded.  But
1332 if <CODE>dcgettext</CODE> is not called the program also cannot find the
1333 <CODE>LANGUAGE</CODE> variable be changed (see section <A HREF="gettext_10.html#SEC171">10.2.7  Optimization of the *gettext functions</A>).  A
1334 solution for this is very easy.  Include the following code in the
1335 language switching function.
1336
1337
1338 <PRE>
1339   /* Change language.  */
1340   setenv ("LANGUAGE", "fr", 1);
1341
1342   /* Make change known.  */
1343   {
1344     extern int  _nl_msg_cat_cntr;
1345     ++_nl_msg_cat_cntr;
1346   }
1347 </PRE>
1348
1349 <A NAME="IDX1022"></A>
1350 The variable <CODE>_nl_msg_cat_cntr</CODE> is defined in <TT>`loadmsgcat.c&acute;</TT>.
1351 You don't need to know what this is for.  But it can be used to detect
1352 whether a <CODE>gettext</CODE> implementation is GNU gettext and not non-GNU
1353 system's native gettext implementation.
1354
1355 </UL>
1356
1357
1358
1359 <H2><A NAME="SEC175" HREF="gettext_toc.html#TOC175">10.6  Temporary Notes for the Programmers Chapter</A></H2>
1360
1361
1362
1363 <H3><A NAME="SEC176" HREF="gettext_toc.html#TOC176">10.6.1  Temporary - Two Possible Implementations</A></H3>
1364
1365 <P>
1366 There are two competing methods for language independent messages:
1367 the X/Open <CODE>catgets</CODE> method, and the Uniforum <CODE>gettext</CODE>
1368 method.  The <CODE>catgets</CODE> method indexes messages by integers; the
1369 <CODE>gettext</CODE> method indexes them by their English translations.
1370 The <CODE>catgets</CODE> method has been around longer and is supported
1371 by more vendors.  The <CODE>gettext</CODE> method is supported by Sun,
1372 and it has been heard that the COSE multi-vendor initiative is
1373 supporting it.  Neither method is a POSIX standard; the POSIX.1
1374 committee had a lot of disagreement in this area.
1375
1376 </P>
1377 <P>
1378 Neither one is in the POSIX standard.  There was much disagreement
1379 in the POSIX.1 committee about using the <CODE>gettext</CODE> routines
1380 vs. <CODE>catgets</CODE> (XPG).  In the end the committee couldn't
1381 agree on anything, so no messaging system was included as part
1382 of the standard.  I believe the informative annex of the standard
1383 includes the XPG3 messaging interfaces, "...as an example of
1384 a messaging system that has been implemented..."
1385
1386 </P>
1387 <P>
1388 They were very careful not to say anywhere that you should use one
1389 set of interfaces over the other.  For more on this topic please
1390 see the Programming for Internationalization FAQ.
1391
1392 </P>
1393
1394
1395 <H3><A NAME="SEC177" HREF="gettext_toc.html#TOC177">10.6.2  Temporary - About <CODE>catgets</CODE></A></H3>
1396
1397 <P>
1398 There have been a few discussions of late on the use of
1399 <CODE>catgets</CODE> as a base.  I think it important to present both
1400 sides of the argument and hence am opting to play devil's advocate
1401 for a little bit.
1402
1403 </P>
1404 <P>
1405 I'll not deny the fact that <CODE>catgets</CODE> could have been designed
1406 a lot better.  It currently has quite a number of limitations and
1407 these have already been pointed out.
1408
1409 </P>
1410 <P>
1411 However there is a great deal to be said for consistency and
1412 standardization.  A common recurring problem when writing Unix
1413 software is the myriad portability problems across Unix platforms.
1414 It seems as if every Unix vendor had a look at the operating system
1415 and found parts they could improve upon.  Undoubtedly, these
1416 modifications are probably innovative and solve real problems.
1417 However, software developers have a hard time keeping up with all
1418 these changes across so many platforms.
1419
1420 </P>
1421 <P>
1422 And this has prompted the Unix vendors to begin to standardize their
1423 systems.  Hence the impetus for Spec1170.  Every major Unix vendor
1424 has committed to supporting this standard and every Unix software
1425 developer waits with glee the day they can write software to this
1426 standard and simply recompile (without having to use autoconf)
1427 across different platforms.
1428
1429 </P>
1430 <P>
1431 As I understand it, Spec1170 is roughly based upon version 4 of the
1432 X/Open Portability Guidelines (XPG4).  Because <CODE>catgets</CODE> and
1433 friends are defined in XPG4, I'm led to believe that <CODE>catgets</CODE>
1434 is a part of Spec1170 and hence will become a standardized component
1435 of all Unix systems.
1436
1437 </P>
1438
1439
1440 <H3><A NAME="SEC178" HREF="gettext_toc.html#TOC178">10.6.3  Temporary - Why a single implementation</A></H3>
1441
1442 <P>
1443 Now it seems kind of wasteful to me to have two different systems
1444 installed for accessing message catalogs.  If we do want to remedy
1445 <CODE>catgets</CODE> deficiencies why don't we try to expand <CODE>catgets</CODE>
1446 (in a compatible manner) rather than implement an entirely new system.
1447 Otherwise, we'll end up with two message catalog access systems installed
1448 with an operating system - one set of routines for packages using GNU
1449 <CODE>gettext</CODE> for their internationalization, and another set of routines
1450 (catgets) for all other software.  Bloated?
1451
1452 </P>
1453 <P>
1454 Supposing another catalog access system is implemented.  Which do
1455 we recommend?  At least for Linux, we need to attract as many
1456 software developers as possible.  Hence we need to make it as easy
1457 for them to port their software as possible.  Which means supporting
1458 <CODE>catgets</CODE>.  We will be implementing the <CODE>libintl</CODE> code
1459 within our <CODE>libc</CODE>, but does this mean we also have to incorporate
1460 another message catalog access scheme within our <CODE>libc</CODE> as well?
1461 And what about people who are going to be using the <CODE>libintl</CODE>
1462 + non-<CODE>catgets</CODE> routines.  When they port their software to
1463 other platforms, they're now going to have to include the front-end
1464 (<CODE>libintl</CODE>) code plus the back-end code (the non-<CODE>catgets</CODE>
1465 access routines) with their software instead of just including the
1466 <CODE>libintl</CODE> code with their software.
1467
1468 </P>
1469 <P>
1470 Message catalog support is however only the tip of the iceberg.
1471 What about the data for the other locale categories.  They also have
1472 a number of deficiencies.  Are we going to abandon them as well and
1473 develop another duplicate set of routines (should <CODE>libintl</CODE>
1474 expand beyond message catalog support)?
1475
1476 </P>
1477 <P>
1478 Like many parts of Unix that can be improved upon, we're stuck with balancing
1479 compatibility with the past with useful improvements and innovations for
1480 the future.
1481
1482 </P>
1483
1484
1485 <H3><A NAME="SEC179" HREF="gettext_toc.html#TOC179">10.6.4  Temporary - Notes</A></H3>
1486
1487 <P>
1488 X/Open agreed very late on the standard form so that many
1489 implementations differ from the final form.  Both of my system (old
1490 Linux catgets and Ultrix-4) have a strange variation.
1491
1492 </P>
1493 <P>
1494 OK.  After incorporating the last changes I have to spend some time on
1495 making the GNU/Linux <CODE>libc</CODE> <CODE>gettext</CODE> functions.  So in future
1496 Solaris is not the only system having <CODE>gettext</CODE>.
1497
1498 </P>
1499 <P><HR><P>
1500 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>.
1501 </BODY>
1502 </HTML>