1<HTML> 2<HEAD> 3<!-- This HTML file has been created by texi2html 1.52b 4 from gettext.texi on 27 November 2006 --> 5 6<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8"> 7<TITLE>GNU gettext utilities - 15 Other Programming Languages</TITLE> 8</HEAD> 9<BODY> 10Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_14.html">previous</A>, <A HREF="gettext_16.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. 11<P><HR><P> 12 13 14<H1><A NAME="SEC229" HREF="gettext_toc.html#TOC229">15 Other Programming Languages</A></H1> 15 16<P> 17While the presentation of <CODE>gettext</CODE> focuses mostly on C and 18implicitly applies to C++ as well, its scope is far broader than that: 19Many programming languages, scripting languages and other textual data 20like GUI resources or package descriptions can make use of the gettext 21approach. 22 23</P> 24 25 26 27<H2><A NAME="SEC230" HREF="gettext_toc.html#TOC230">15.1 The Language Implementor's View</A></H2> 28<P> 29<A NAME="IDX1111"></A> 30<A NAME="IDX1112"></A> 31 32</P> 33<P> 34All programming and scripting languages that have the notion of strings 35are eligible to supporting <CODE>gettext</CODE>. Supporting <CODE>gettext</CODE> 36means the following: 37 38</P> 39 40<OL> 41<LI> 42 43You should add to the language a syntax for translatable strings. In 44principle, a function call of <CODE>gettext</CODE> would do, but a shorthand 45syntax helps keeping the legibility of internationalized programs. For 46example, in C we use the syntax <CODE>_("string")</CODE>, and in GNU awk we use 47the shorthand <CODE>_"string"</CODE>. 48 49<LI> 50 51You should arrange that evaluation of such a translatable string at 52runtime calls the <CODE>gettext</CODE> function, or performs equivalent 53processing. 54 55<LI> 56 57Similarly, you should make the functions <CODE>ngettext</CODE>, 58<CODE>dcgettext</CODE>, <CODE>dcngettext</CODE> available from within the language. 59These functions are less often used, but are nevertheless necessary for 60particular purposes: <CODE>ngettext</CODE> for correct plural handling, and 61<CODE>dcgettext</CODE> and <CODE>dcngettext</CODE> for obeying other locale 62environment variables than <CODE>LC_MESSAGES</CODE>, such as <CODE>LC_TIME</CODE> or 63<CODE>LC_MONETARY</CODE>. For these latter functions, you need to make the 64<CODE>LC_*</CODE> constants, available in the C header <CODE><locale.h></CODE>, 65referenceable from within the language, usually either as enumeration 66values or as strings. 67 68<LI> 69 70You should allow the programmer to designate a message domain, either by 71making the <CODE>textdomain</CODE> function available from within the 72language, or by introducing a magic variable called <CODE>TEXTDOMAIN</CODE>. 73Similarly, you should allow the programmer to designate where to search 74for message catalogs, by providing access to the <CODE>bindtextdomain</CODE> 75function. 76 77<LI> 78 79You should either perform a <CODE>setlocale (LC_ALL, "")</CODE> call during 80the startup of your language runtime, or allow the programmer to do so. 81Remember that gettext will act as a no-op if the <CODE>LC_MESSAGES</CODE> and 82<CODE>LC_CTYPE</CODE> locale facets are not both set. 83 84<LI> 85 86A programmer should have a way to extract translatable strings from a 87program into a PO file. The GNU <CODE>xgettext</CODE> program is being 88extended to support very different programming languages. Please 89contact the GNU <CODE>gettext</CODE> maintainers to help them doing this. If 90the string extractor is best integrated into your language's parser, GNU 91<CODE>xgettext</CODE> can function as a front end to your string extractor. 92 93<LI> 94 95The language's library should have a string formatting facility where 96the arguments of a format string are denoted by a positional number or a 97name. This is needed because for some languages and some messages with 98more than one substitutable argument, the translation will need to 99output the substituted arguments in different order. See section <A HREF="gettext_4.html#SEC17">4.6 Special Comments preceding Keywords</A>. 100 101<LI> 102 103If the language has more than one implementation, and not all of the 104implementations use <CODE>gettext</CODE>, but the programs should be portable 105across implementations, you should provide a no-i18n emulation, that 106makes the other implementations accept programs written for yours, 107without actually translating the strings. 108 109<LI> 110 111To help the programmer in the task of marking translatable strings, 112which is sometimes performed using the Emacs PO mode (see section <A HREF="gettext_4.html#SEC16">4.5 Marking Translatable Strings</A>), 113you are welcome to 114contact the GNU <CODE>gettext</CODE> maintainers, so they can add support for 115your language to <TT>‘po-mode.el’</TT>. 116</OL> 117 118<P> 119On the implementation side, three approaches are possible, with 120different effects on portability and copyright: 121 122</P> 123 124<UL> 125<LI> 126 127You may integrate the GNU <CODE>gettext</CODE>'s <TT>‘intl/’</TT> directory in 128your package, as described in section <A HREF="gettext_13.html#SEC196">13 The Maintainer's View</A>. This allows you to 129have internationalization on all kinds of platforms. Note that when you 130then distribute your package, it legally falls under the GNU General 131Public License, and the GNU project will be glad about your contribution 132to the Free Software pool. 133 134<LI> 135 136You may link against GNU <CODE>gettext</CODE> functions if they are found in 137the C library. For example, an autoconf test for <CODE>gettext()</CODE> and 138<CODE>ngettext()</CODE> will detect this situation. For the moment, this test 139will succeed on GNU systems and not on other platforms. No severe 140copyright restrictions apply. 141 142<LI> 143 144You may emulate or reimplement the GNU <CODE>gettext</CODE> functionality. 145This has the advantage of full portability and no copyright 146restrictions, but also the drawback that you have to reimplement the GNU 147<CODE>gettext</CODE> features (such as the <CODE>LANGUAGE</CODE> environment 148variable, the locale aliases database, the automatic charset conversion, 149and plural handling). 150</UL> 151 152 153 154<H2><A NAME="SEC231" HREF="gettext_toc.html#TOC231">15.2 The Programmer's View</A></H2> 155 156<P> 157For the programmer, the general procedure is the same as for the C 158language. The Emacs PO mode marking supports other languages, and the GNU 159<CODE>xgettext</CODE> string extractor recognizes other languages based on the 160file extension or a command-line option. In some languages, 161<CODE>setlocale</CODE> is not needed because it is already performed by the 162underlying language runtime. 163 164</P> 165 166 167<H2><A NAME="SEC232" HREF="gettext_toc.html#TOC232">15.3 The Translator's View</A></H2> 168 169<P> 170The translator works exactly as in the C language case. The only 171difference is that when translating format strings, she has to be aware 172of the language's particular syntax for positional arguments in format 173strings. 174 175</P> 176 177 178 179<H3><A NAME="SEC233" HREF="gettext_toc.html#TOC233">15.3.1 C Format Strings</A></H3> 180 181<P> 182C format strings are described in POSIX (IEEE P1003.1 2001), section 183XSH 3 fprintf(), 184<A HREF="http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html">http://www.opengroup.org/onlinepubs/007904975/functions/fprintf.html</A>. 185See also the fprintf() manual page, 186<A HREF="http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php">http://www.linuxvalley.it/encyclopedia/ldp/manpage/man3/printf.3.php</A>, 187<A HREF="http://informatik.fh-wuerzburg.de/student/i510/man/printf.html">http://informatik.fh-wuerzburg.de/student/i510/man/printf.html</A>. 188 189</P> 190<P> 191Although format strings with positions that reorder arguments, such as 192 193</P> 194 195<PRE> 196"Only %2$d bytes free on '%1$s'." 197</PRE> 198 199<P> 200which is semantically equivalent to 201 202</P> 203 204<PRE> 205"'%s' has only %d bytes free." 206</PRE> 207 208<P> 209are a POSIX/XSI feature and not specified by ISO C 99, translators can rely 210on this reordering ability: On the few platforms where <CODE>printf()</CODE>, 211<CODE>fprintf()</CODE> etc. don't support this feature natively, <TT>‘libintl.a’</TT> 212or <TT>‘libintl.so’</TT> provides replacement functions, and GNU <CODE><libintl.h></CODE> 213activates these replacement functions automatically. 214 215</P> 216<P> 217<A NAME="IDX1113"></A> 218<A NAME="IDX1114"></A> 219As a special feature for Farsi (Persian) and maybe Arabic, translators can 220insert an <SAMP>‘I’</SAMP> flag into numeric format directives. For example, the 221translation of <CODE>"%d"</CODE> can be <CODE>"%Id"</CODE>. The effect of this flag, 222on systems with GNU <CODE>libc</CODE>, is that in the output, the ASCII digits are 223replaced with the <SAMP>‘outdigits’</SAMP> defined in the <CODE>LC_CTYPE</CODE> locale 224facet. On other systems, the <CODE>gettext</CODE> function removes this flag, 225so that it has no effect. 226 227</P> 228<P> 229Note that the programmer should <EM>not</EM> put this flag into the 230untranslated string. (Putting the <SAMP>‘I’</SAMP> format directive flag into an 231<VAR>msgid</VAR> string would lead to undefined behaviour on platforms without 232glibc when NLS is disabled.) 233 234</P> 235 236 237<H3><A NAME="SEC234" HREF="gettext_toc.html#TOC234">15.3.2 Objective C Format Strings</A></H3> 238 239<P> 240Objective C format strings are like C format strings. They support an 241additional format directive: "$@", which when executed consumes an argument 242of type <CODE>Object *</CODE>. 243 244</P> 245 246 247<H3><A NAME="SEC235" HREF="gettext_toc.html#TOC235">15.3.3 Shell Format Strings</A></H3> 248 249<P> 250Shell format strings, as supported by GNU gettext and the <SAMP>‘envsubst’</SAMP> 251program, are strings with references to shell variables in the form 252<CODE>$<VAR>variable</VAR></CODE> or <CODE>${<VAR>variable</VAR>}</CODE>. References of the form 253<CODE>${<VAR>variable</VAR>-<VAR>default</VAR>}</CODE>, 254<CODE>${<VAR>variable</VAR>:-<VAR>default</VAR>}</CODE>, 255<CODE>${<VAR>variable</VAR>=<VAR>default</VAR>}</CODE>, 256<CODE>${<VAR>variable</VAR>:=<VAR>default</VAR>}</CODE>, 257<CODE>${<VAR>variable</VAR>+<VAR>replacement</VAR>}</CODE>, 258<CODE>${<VAR>variable</VAR>:+<VAR>replacement</VAR>}</CODE>, 259<CODE>${<VAR>variable</VAR>?<VAR>ignored</VAR>}</CODE>, 260<CODE>${<VAR>variable</VAR>:?<VAR>ignored</VAR>}</CODE>, 261that would be valid inside shell scripts, are not supported. The 262<VAR>variable</VAR> names must consist solely of alphanumeric or underscore 263ASCII characters, not start with a digit and be nonempty; otherwise such 264a variable reference is ignored. 265 266</P> 267 268 269<H3><A NAME="SEC236" HREF="gettext_toc.html#TOC236">15.3.4 Python Format Strings</A></H3> 270 271<P> 272Python format strings are described in 273Python Library reference / 2742. Built-in Types, Exceptions and Functions / 2752.2. Built-in Types / 2762.2.6. Sequence Types / 2772.2.6.2. String Formatting Operations. 278<A HREF="http://www.python.org/doc/2.2.1/lib/typesseq-strings.html">http://www.python.org/doc/2.2.1/lib/typesseq-strings.html</A>. 279 280</P> 281 282 283<H3><A NAME="SEC237" HREF="gettext_toc.html#TOC237">15.3.5 Lisp Format Strings</A></H3> 284 285<P> 286Lisp format strings are described in the Common Lisp HyperSpec, 287chapter 22.3 Formatted Output, 288<A HREF="http://www.lisp.org/HyperSpec/Body/sec_22-3.html">http://www.lisp.org/HyperSpec/Body/sec_22-3.html</A>. 289 290</P> 291 292 293<H3><A NAME="SEC238" HREF="gettext_toc.html#TOC238">15.3.6 Emacs Lisp Format Strings</A></H3> 294 295<P> 296Emacs Lisp format strings are documented in the Emacs Lisp reference, 297section Formatting Strings, 298<A HREF="http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75">http://www.gnu.org/manual/elisp-manual-21-2.8/html_chapter/elisp_4.html#SEC75</A>. 299Note that as of version 21, XEmacs supports numbered argument specifications 300in format strings while FSF Emacs doesn't. 301 302</P> 303 304 305<H3><A NAME="SEC239" HREF="gettext_toc.html#TOC239">15.3.7 librep Format Strings</A></H3> 306 307<P> 308librep format strings are documented in the librep manual, section 309Formatted Output, 310<A HREF="http://librep.sourceforge.net/librep-manual.html#Formatted%20Output">http://librep.sourceforge.net/librep-manual.html#Formatted%20Output</A>, 311<A HREF="http://www.gwinnup.org/research/docs/librep.html#SEC122">http://www.gwinnup.org/research/docs/librep.html#SEC122</A>. 312 313</P> 314 315 316<H3><A NAME="SEC240" HREF="gettext_toc.html#TOC240">15.3.8 Scheme Format Strings</A></H3> 317 318<P> 319Scheme format strings are documented in the SLIB manual, section 320Format Specification. 321 322</P> 323 324 325<H3><A NAME="SEC241" HREF="gettext_toc.html#TOC241">15.3.9 Smalltalk Format Strings</A></H3> 326 327<P> 328Smalltalk format strings are described in the GNU Smalltalk documentation, 329class <CODE>CharArray</CODE>, methods <SAMP>‘bindWith:’</SAMP> and 330<SAMP>‘bindWithArguments:’</SAMP>. 331<A HREF="http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238">http://www.gnu.org/software/smalltalk/gst-manual/gst_68.html#SEC238</A>. 332In summary, a directive starts with <SAMP>‘%’</SAMP> and is followed by <SAMP>‘%’</SAMP> 333or a nonzero digit (<SAMP>‘1’</SAMP> to <SAMP>‘9’</SAMP>). 334 335</P> 336 337 338<H3><A NAME="SEC242" HREF="gettext_toc.html#TOC242">15.3.10 Java Format Strings</A></H3> 339 340<P> 341Java format strings are described in the JDK documentation for class 342<CODE>java.text.MessageFormat</CODE>, 343<A HREF="http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html">http://java.sun.com/j2se/1.4/docs/api/java/text/MessageFormat.html</A>. 344See also the ICU documentation 345<A HREF="http://oss.software.ibm.com/icu/apiref/classMessageFormat.html">http://oss.software.ibm.com/icu/apiref/classMessageFormat.html</A>. 346 347</P> 348 349 350<H3><A NAME="SEC243" HREF="gettext_toc.html#TOC243">15.3.11 C# Format Strings</A></H3> 351 352<P> 353C# format strings are described in the .NET documentation for class 354<CODE>System.String</CODE> and in 355<A HREF="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp">http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpConFormattingOverview.asp</A>. 356 357</P> 358 359 360<H3><A NAME="SEC244" HREF="gettext_toc.html#TOC244">15.3.12 awk Format Strings</A></H3> 361 362<P> 363awk format strings are described in the gawk documentation, section 364Printf, 365<A HREF="http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf">http://www.gnu.org/manual/gawk/html_node/Printf.html#Printf</A>. 366 367</P> 368 369 370<H3><A NAME="SEC245" HREF="gettext_toc.html#TOC245">15.3.13 Object Pascal Format Strings</A></H3> 371 372<P> 373Where is this documented? 374 375</P> 376 377 378<H3><A NAME="SEC246" HREF="gettext_toc.html#TOC246">15.3.14 YCP Format Strings</A></H3> 379 380<P> 381YCP sformat strings are described in the libycp documentation 382<A HREF="file:/usr/share/doc/packages/libycp/YCP-builtins.html">file:/usr/share/doc/packages/libycp/YCP-builtins.html</A>. 383In summary, a directive starts with <SAMP>‘%’</SAMP> and is followed by <SAMP>‘%’</SAMP> 384or a nonzero digit (<SAMP>‘1’</SAMP> to <SAMP>‘9’</SAMP>). 385 386</P> 387 388 389<H3><A NAME="SEC247" HREF="gettext_toc.html#TOC247">15.3.15 Tcl Format Strings</A></H3> 390 391<P> 392Tcl format strings are described in the <TT>‘format.n’</TT> manual page, 393<A HREF="http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm">http://www.scriptics.com/man/tcl8.3/TclCmd/format.htm</A>. 394 395</P> 396 397 398<H3><A NAME="SEC248" HREF="gettext_toc.html#TOC248">15.3.16 Perl Format Strings</A></H3> 399 400<P> 401There are two kinds format strings in Perl: those acceptable to the 402Perl built-in function <CODE>printf</CODE>, labelled as <SAMP>‘perl-format’</SAMP>, 403and those acceptable to the <CODE>libintl-perl</CODE> function <CODE>__x</CODE>, 404labelled as <SAMP>‘perl-brace-format’</SAMP>. 405 406</P> 407<P> 408Perl <CODE>printf</CODE> format strings are described in the <CODE>sprintf</CODE> 409section of <SAMP>‘man perlfunc’</SAMP>. 410 411</P> 412<P> 413Perl brace format strings are described in the 414<TT>‘Locale::TextDomain(3pm)’</TT> manual page of the CPAN package 415libintl-perl. In brief, Perl format uses placeholders put between 416braces (<SAMP>‘{’</SAMP> and <SAMP>‘}’</SAMP>). The placeholder must have the syntax 417of simple identifiers. 418 419</P> 420 421 422<H3><A NAME="SEC249" HREF="gettext_toc.html#TOC249">15.3.17 PHP Format Strings</A></H3> 423 424<P> 425PHP format strings are described in the documentation of the PHP function 426<CODE>sprintf</CODE>, in <TT>‘phpdoc/manual/function.sprintf.html’</TT> or 427<A HREF="http://www.php.net/manual/en/function.sprintf.php">http://www.php.net/manual/en/function.sprintf.php</A>. 428 429</P> 430 431 432<H3><A NAME="SEC250" HREF="gettext_toc.html#TOC250">15.3.18 GCC internal Format Strings</A></H3> 433 434<P> 435These format strings are used inside the GCC sources. In such a format 436string, a directive starts with <SAMP>‘%’</SAMP>, is optionally followed by a 437size specifier <SAMP>‘l’</SAMP>, an optional flag <SAMP>‘+’</SAMP>, another optional flag 438<SAMP>‘#’</SAMP>, and is finished by a specifier: <SAMP>‘%’</SAMP> denotes a literal 439percent sign, <SAMP>‘c’</SAMP> denotes a character, <SAMP>‘s’</SAMP> denotes a string, 440<SAMP>‘i’</SAMP> and <SAMP>‘d’</SAMP> denote an integer, <SAMP>‘o’</SAMP>, <SAMP>‘u’</SAMP>, <SAMP>‘x’</SAMP> 441denote an unsigned integer, <SAMP>‘.*s’</SAMP> denotes a string preceded by a 442width specification, <SAMP>‘H’</SAMP> denotes a <SAMP>‘location_t *’</SAMP> pointer, 443<SAMP>‘D’</SAMP> denotes a general declaration, <SAMP>‘F’</SAMP> denotes a function 444declaration, <SAMP>‘T’</SAMP> denotes a type, <SAMP>‘A’</SAMP> denotes a function argument, 445<SAMP>‘C’</SAMP> denotes a tree code, <SAMP>‘E’</SAMP> denotes an expression, <SAMP>‘L’</SAMP> 446denotes a programming language, <SAMP>‘O’</SAMP> denotes a binary operator, 447<SAMP>‘P’</SAMP> denotes a function parameter, <SAMP>‘Q’</SAMP> denotes an assignment 448operator, <SAMP>‘V’</SAMP> denotes a const/volatile qualifier. 449 450</P> 451 452 453<H3><A NAME="SEC251" HREF="gettext_toc.html#TOC251">15.3.19 Qt Format Strings</A></H3> 454 455<P> 456Qt format strings are described in the documentation of the QString class 457<A HREF="file:/usr/lib/qt-3.0.5/doc/html/qstring.html">file:/usr/lib/qt-3.0.5/doc/html/qstring.html</A>. 458In summary, a directive consists of a <SAMP>‘%’</SAMP> followed by a digit. The same 459directive cannot occur more than once in a format string. 460 461</P> 462 463 464<H3><A NAME="SEC252" HREF="gettext_toc.html#TOC252">15.3.20 Boost Format Strings</A></H3> 465 466<P> 467Boost format strings are described in the documentation of the 468<CODE>boost::format</CODE> class, at 469<A HREF="http://www.boost.org/libs/format/doc/format.html">http://www.boost.org/libs/format/doc/format.html</A>. 470In summary, a directive has either the same syntax as in a C format string, 471such as <SAMP>‘%1$+5d’</SAMP>, or may be surrounded by vertical bars, such as 472<SAMP>‘%|1$+5d|’</SAMP> or <SAMP>‘%|1$+5|’</SAMP>, or consists of just an argument number 473between percent signs, such as <SAMP>‘%1%’</SAMP>. 474 475</P> 476 477 478<H2><A NAME="SEC253" HREF="gettext_toc.html#TOC253">15.4 The Maintainer's View</A></H2> 479 480<P> 481For the maintainer, the general procedure differs from the C language 482case in two ways. 483 484</P> 485 486<UL> 487<LI> 488 489For those languages that don't use GNU gettext, the <TT>‘intl/’</TT> directory 490is not needed and can be omitted. This means that the maintainer calls the 491<CODE>gettextize</CODE> program without the <SAMP>‘--intl’</SAMP> option, and that he 492invokes the <CODE>AM_GNU_GETTEXT</CODE> autoconf macro via 493<SAMP>‘AM_GNU_GETTEXT([external])’</SAMP>. 494 495<LI> 496 497If only a single programming language is used, the <CODE>XGETTEXT_OPTIONS</CODE> 498variable in <TT>‘po/Makevars’</TT> (see section <A HREF="gettext_13.html#SEC203">13.4.3 <TT>‘Makevars’</TT> in <TT>‘po/’</TT></A>) should be adjusted to 499match the <CODE>xgettext</CODE> options for that particular programming language. 500If the package uses more than one programming language with <CODE>gettext</CODE> 501support, it becomes necessary to change the POT file construction rule 502in <TT>‘po/Makefile.in.in’</TT>. It is recommended to make one <CODE>xgettext</CODE> 503invocation per programming language, each with the options appropriate for 504that language, and to combine the resulting files using <CODE>msgcat</CODE>. 505</UL> 506 507 508 509<H2><A NAME="SEC254" HREF="gettext_toc.html#TOC254">15.5 Individual Programming Languages</A></H2> 510 511 512 513<H3><A NAME="SEC255" HREF="gettext_toc.html#TOC255">15.5.1 C, C++, Objective C</A></H3> 514<P> 515<A NAME="IDX1115"></A> 516 517</P> 518<DL COMPACT> 519 520<DT>RPMs 521<DD> 522gcc, gpp, gobjc, glibc, gettext 523 524<DT>File extension 525<DD> 526For C: <CODE>c</CODE>, <CODE>h</CODE>. 527<BR>For C++: <CODE>C</CODE>, <CODE>c++</CODE>, <CODE>cc</CODE>, <CODE>cxx</CODE>, <CODE>cpp</CODE>, <CODE>hpp</CODE>. 528<BR>For Objective C: <CODE>m</CODE>. 529 530<DT>String syntax 531<DD> 532<CODE>"abc"</CODE> 533 534<DT>gettext shorthand 535<DD> 536<CODE>_("abc")</CODE> 537 538<DT>gettext/ngettext functions 539<DD> 540<CODE>gettext</CODE>, <CODE>dgettext</CODE>, <CODE>dcgettext</CODE>, <CODE>ngettext</CODE>, 541<CODE>dngettext</CODE>, <CODE>dcngettext</CODE> 542 543<DT>textdomain 544<DD> 545<CODE>textdomain</CODE> function 546 547<DT>bindtextdomain 548<DD> 549<CODE>bindtextdomain</CODE> function 550 551<DT>setlocale 552<DD> 553Programmer must call <CODE>setlocale (LC_ALL, "")</CODE> 554 555<DT>Prerequisite 556<DD> 557<CODE>#include <libintl.h></CODE> 558<BR><CODE>#include <locale.h></CODE> 559<BR><CODE>#define _(string) gettext (string)</CODE> 560 561<DT>Use or emulate GNU gettext 562<DD> 563Use 564 565<DT>Extractor 566<DD> 567<CODE>xgettext -k_</CODE> 568 569<DT>Formatting with positions 570<DD> 571<CODE>fprintf "%2$d %1$d"</CODE> 572<BR>In C++: <CODE>autosprintf "%2$d %1$d"</CODE> 573(see section ‘Introduction’ in <CITE>GNU autosprintf</CITE>) 574 575<DT>Portability 576<DD> 577autoconf (gettext.m4) and #if ENABLE_NLS 578 579<DT>po-mode marking 580<DD> 581yes 582</DL> 583 584<P> 585The following examples are available in the <TT>‘examples’</TT> directory: 586<CODE>hello-c</CODE>, <CODE>hello-c-gnome</CODE>, <CODE>hello-c++</CODE>, <CODE>hello-c++-qt</CODE>, 587<CODE>hello-c++-kde</CODE>, <CODE>hello-c++-gnome</CODE>, <CODE>hello-c++-wxwidgets</CODE>, 588<CODE>hello-objc</CODE>, <CODE>hello-objc-gnustep</CODE>, <CODE>hello-objc-gnome</CODE>. 589 590</P> 591 592 593<H3><A NAME="SEC256" HREF="gettext_toc.html#TOC256">15.5.2 sh - Shell Script</A></H3> 594<P> 595<A NAME="IDX1116"></A> 596 597</P> 598<DL COMPACT> 599 600<DT>RPMs 601<DD> 602bash, gettext 603 604<DT>File extension 605<DD> 606<CODE>sh</CODE> 607 608<DT>String syntax 609<DD> 610<CODE>"abc"</CODE>, <CODE>'abc'</CODE>, <CODE>abc</CODE> 611 612<DT>gettext shorthand 613<DD> 614<CODE>"`gettext \"abc\"`"</CODE> 615 616<DT>gettext/ngettext functions 617<DD> 618<A NAME="IDX1117"></A> 619<A NAME="IDX1118"></A> 620<CODE>gettext</CODE>, <CODE>ngettext</CODE> programs 621<BR><CODE>eval_gettext</CODE>, <CODE>eval_ngettext</CODE> shell functions 622 623<DT>textdomain 624<DD> 625<A NAME="IDX1119"></A> 626environment variable <CODE>TEXTDOMAIN</CODE> 627 628<DT>bindtextdomain 629<DD> 630<A NAME="IDX1120"></A> 631environment variable <CODE>TEXTDOMAINDIR</CODE> 632 633<DT>setlocale 634<DD> 635automatic 636 637<DT>Prerequisite 638<DD> 639<CODE>. gettext.sh</CODE> 640 641<DT>Use or emulate GNU gettext 642<DD> 643use 644 645<DT>Extractor 646<DD> 647<CODE>xgettext</CODE> 648 649<DT>Formatting with positions 650<DD> 651--- 652 653<DT>Portability 654<DD> 655fully portable 656 657<DT>po-mode marking 658<DD> 659--- 660</DL> 661 662<P> 663An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-sh</CODE>. 664 665</P> 666 667 668 669<H4><A NAME="SEC257" HREF="gettext_toc.html#TOC257">15.5.2.1 Preparing Shell Scripts for Internationalization</A></H4> 670<P> 671<A NAME="IDX1121"></A> 672 673</P> 674<P> 675Preparing a shell script for internationalization is conceptually similar 676to the steps described in section <A HREF="gettext_4.html#SEC11">4 Preparing Program Sources</A>. The concrete steps for shell 677scripts are as follows. 678 679</P> 680 681<OL> 682<LI> 683 684Insert the line 685 686 687<PRE> 688. gettext.sh 689</PRE> 690 691near the top of the script. <CODE>gettext.sh</CODE> is a shell function library 692that provides the functions 693<CODE>eval_gettext</CODE> (see section <A HREF="gettext_15.html#SEC262">15.5.2.6 Invoking the <CODE>eval_gettext</CODE> function</A>) and 694<CODE>eval_ngettext</CODE> (see section <A HREF="gettext_15.html#SEC263">15.5.2.7 Invoking the <CODE>eval_ngettext</CODE> function</A>). 695You have to ensure that <CODE>gettext.sh</CODE> can be found in the <CODE>PATH</CODE>. 696 697<LI> 698 699Set and export the <CODE>TEXTDOMAIN</CODE> and <CODE>TEXTDOMAINDIR</CODE> environment 700variables. Usually <CODE>TEXTDOMAIN</CODE> is the package or program name, and 701<CODE>TEXTDOMAINDIR</CODE> is the absolute pathname corresponding to 702<CODE>$prefix/share/locale</CODE>, where <CODE>$prefix</CODE> is the installation location. 703 704 705<PRE> 706TEXTDOMAIN=@PACKAGE@ 707export TEXTDOMAIN 708TEXTDOMAINDIR=@LOCALEDIR@ 709export TEXTDOMAINDIR 710</PRE> 711 712<LI> 713 714Prepare the strings for translation, as described in section <A HREF="gettext_4.html#SEC14">4.3 Preparing Translatable Strings</A>. 715 716<LI> 717 718Simplify translatable strings so that they don't contain command substitution 719(<CODE>"`...`"</CODE> or <CODE>"$(...)"</CODE>), variable access with defaulting (like 720<CODE>${<VAR>variable</VAR>-<VAR>default</VAR>}</CODE>), access to positional arguments 721(like <CODE>$0</CODE>, <CODE>$1</CODE>, ...) or highly volatile shell variables (like 722<CODE>$?</CODE>). This can always be done through simple local code restructuring. 723For example, 724 725 726<PRE> 727echo "Usage: $0 [OPTION] FILE..." 728</PRE> 729 730becomes 731 732 733<PRE> 734program_name=$0 735echo "Usage: $program_name [OPTION] FILE..." 736</PRE> 737 738Similarly, 739 740 741<PRE> 742echo "Remaining files: `ls | wc -l`" 743</PRE> 744 745becomes 746 747 748<PRE> 749filecount="`ls | wc -l`" 750echo "Remaining files: $filecount" 751</PRE> 752 753<LI> 754 755For each translatable string, change the output command <SAMP>‘echo’</SAMP> or 756<SAMP>‘$echo’</SAMP> to <SAMP>‘gettext’</SAMP> (if the string contains no references to 757shell variables) or to <SAMP>‘eval_gettext’</SAMP> (if it refers to shell variables), 758followed by a no-argument <SAMP>‘echo’</SAMP> command (to account for the terminating 759newline). Similarly, for cases with plural handling, replace a conditional 760<SAMP>‘echo’</SAMP> command with an invocation of <SAMP>‘ngettext’</SAMP> or 761<SAMP>‘eval_ngettext’</SAMP>, followed by a no-argument <SAMP>‘echo’</SAMP> command. 762 763When doing this, you also need to add an extra backslash before the dollar 764sign in references to shell variables, so that the <SAMP>‘eval_gettext’</SAMP> 765function receives the translatable string before the variable values are 766substituted into it. For example, 767 768 769<PRE> 770echo "Remaining files: $filecount" 771</PRE> 772 773becomes 774 775 776<PRE> 777eval_gettext "Remaining files: \$filecount"; echo 778</PRE> 779 780If the output command is not <SAMP>‘echo’</SAMP>, you can make it use <SAMP>‘echo’</SAMP> 781nevertheless, through the use of backquotes. However, note that inside 782backquotes, backslashes must be doubled to be effective (because the 783backquoting eats one level of backslashes). For example, assuming that 784<SAMP>‘error’</SAMP> is a shell function that signals an error, 785 786 787<PRE> 788error "file not found: $filename" 789</PRE> 790 791is first transformed into 792 793 794<PRE> 795error "`echo \"file not found: \$filename\"`" 796</PRE> 797 798which then becomes 799 800 801<PRE> 802error "`eval_gettext \"file not found: \\\$filename\"`" 803</PRE> 804 805</OL> 806 807 808 809<H4><A NAME="SEC258" HREF="gettext_toc.html#TOC258">15.5.2.2 Contents of <CODE>gettext.sh</CODE></A></H4> 810 811<P> 812<CODE>gettext.sh</CODE>, contained in the run-time package of GNU gettext, provides 813the following: 814 815</P> 816 817<UL> 818<LI>$echo 819 820The variable <CODE>echo</CODE> is set to a command that outputs its first argument 821and a newline, without interpreting backslashes in the argument string. 822 823<LI>eval_gettext 824 825See section <A HREF="gettext_15.html#SEC262">15.5.2.6 Invoking the <CODE>eval_gettext</CODE> function</A>. 826 827<LI>eval_ngettext 828 829See section <A HREF="gettext_15.html#SEC263">15.5.2.7 Invoking the <CODE>eval_ngettext</CODE> function</A>. 830</UL> 831 832 833 834<H4><A NAME="SEC259" HREF="gettext_toc.html#TOC259">15.5.2.3 Invoking the <CODE>gettext</CODE> program</A></H4> 835 836<P> 837<A NAME="IDX1122"></A> 838<A NAME="IDX1123"></A> 839 840<PRE> 841gettext [<VAR>option</VAR>] [[<VAR>textdomain</VAR>] <VAR>msgid</VAR>] 842gettext [<VAR>option</VAR>] -s [<VAR>msgid</VAR>]... 843</PRE> 844 845<P> 846<A NAME="IDX1124"></A> 847The <CODE>gettext</CODE> program displays the native language translation of a 848textual message. 849 850</P> 851<P> 852<STRONG>Arguments</STRONG> 853 854</P> 855<DL COMPACT> 856 857<DT><SAMP>‘-d <VAR>textdomain</VAR>’</SAMP> 858<DD> 859<DT><SAMP>‘--domain=<VAR>textdomain</VAR>’</SAMP> 860<DD> 861<A NAME="IDX1125"></A> 862<A NAME="IDX1126"></A> 863Retrieve translated messages from <VAR>textdomain</VAR>. Usually a <VAR>textdomain</VAR> 864corresponds to a package, a program, or a module of a program. 865 866<DT><SAMP>‘-e’</SAMP> 867<DD> 868<A NAME="IDX1127"></A> 869Enable expansion of some escape sequences. This option is for compatibility 870with the <SAMP>‘echo’</SAMP> program or shell built-in. The escape sequences 871<SAMP>‘\a’</SAMP>, <SAMP>‘\b’</SAMP>, <SAMP>‘\c’</SAMP>, <SAMP>‘\f’</SAMP>, <SAMP>‘\n’</SAMP>, <SAMP>‘\r’</SAMP>, <SAMP>‘\t’</SAMP>, 872<SAMP>‘\v’</SAMP>, <SAMP>‘\\’</SAMP>, and <SAMP>‘\’</SAMP> followed by one to three octal digits, are 873interpreted like the System V <SAMP>‘echo’</SAMP> program did. 874 875<DT><SAMP>‘-E’</SAMP> 876<DD> 877<A NAME="IDX1128"></A> 878This option is only for compatibility with the <SAMP>‘echo’</SAMP> program or shell 879built-in. It has no effect. 880 881<DT><SAMP>‘-h’</SAMP> 882<DD> 883<DT><SAMP>‘--help’</SAMP> 884<DD> 885<A NAME="IDX1129"></A> 886<A NAME="IDX1130"></A> 887Display this help and exit. 888 889<DT><SAMP>‘-n’</SAMP> 890<DD> 891<A NAME="IDX1131"></A> 892Suppress trailing newline. By default, <CODE>gettext</CODE> adds a newline to 893the output. 894 895<DT><SAMP>‘-V’</SAMP> 896<DD> 897<DT><SAMP>‘--version’</SAMP> 898<DD> 899<A NAME="IDX1132"></A> 900<A NAME="IDX1133"></A> 901Output version information and exit. 902 903<DT><SAMP>‘[<VAR>textdomain</VAR>] <VAR>msgid</VAR>’</SAMP> 904<DD> 905Retrieve translated message corresponding to <VAR>msgid</VAR> from <VAR>textdomain</VAR>. 906 907</DL> 908 909<P> 910If the <VAR>textdomain</VAR> parameter is not given, the domain is determined from 911the environment variable <CODE>TEXTDOMAIN</CODE>. If the message catalog is not 912found in the regular directory, another location can be specified with the 913environment variable <CODE>TEXTDOMAINDIR</CODE>. 914 915</P> 916<P> 917When used with the <CODE>-s</CODE> option the program behaves like the <SAMP>‘echo’</SAMP> 918command. But it does not simply copy its arguments to stdout. Instead those 919messages found in the selected catalog are translated. 920 921</P> 922 923 924<H4><A NAME="SEC260" HREF="gettext_toc.html#TOC260">15.5.2.4 Invoking the <CODE>ngettext</CODE> program</A></H4> 925 926<P> 927<A NAME="IDX1134"></A> 928<A NAME="IDX1135"></A> 929 930<PRE> 931ngettext [<VAR>option</VAR>] [<VAR>textdomain</VAR>] <VAR>msgid</VAR> <VAR>msgid-plural</VAR> <VAR>count</VAR> 932</PRE> 933 934<P> 935<A NAME="IDX1136"></A> 936The <CODE>ngettext</CODE> program displays the native language translation of a 937textual message whose grammatical form depends on a number. 938 939</P> 940<P> 941<STRONG>Arguments</STRONG> 942 943</P> 944<DL COMPACT> 945 946<DT><SAMP>‘-d <VAR>textdomain</VAR>’</SAMP> 947<DD> 948<DT><SAMP>‘--domain=<VAR>textdomain</VAR>’</SAMP> 949<DD> 950<A NAME="IDX1137"></A> 951<A NAME="IDX1138"></A> 952Retrieve translated messages from <VAR>textdomain</VAR>. Usually a <VAR>textdomain</VAR> 953corresponds to a package, a program, or a module of a program. 954 955<DT><SAMP>‘-e’</SAMP> 956<DD> 957<A NAME="IDX1139"></A> 958Enable expansion of some escape sequences. This option is for compatibility 959with the <SAMP>‘gettext’</SAMP> program. The escape sequences 960<SAMP>‘\a’</SAMP>, <SAMP>‘\b’</SAMP>, <SAMP>‘\c’</SAMP>, <SAMP>‘\f’</SAMP>, <SAMP>‘\n’</SAMP>, <SAMP>‘\r’</SAMP>, <SAMP>‘\t’</SAMP>, 961<SAMP>‘\v’</SAMP>, <SAMP>‘\\’</SAMP>, and <SAMP>‘\’</SAMP> followed by one to three octal digits, are 962interpreted like the System V <SAMP>‘echo’</SAMP> program did. 963 964<DT><SAMP>‘-E’</SAMP> 965<DD> 966<A NAME="IDX1140"></A> 967This option is only for compatibility with the <SAMP>‘gettext’</SAMP> program. It has 968no effect. 969 970<DT><SAMP>‘-h’</SAMP> 971<DD> 972<DT><SAMP>‘--help’</SAMP> 973<DD> 974<A NAME="IDX1141"></A> 975<A NAME="IDX1142"></A> 976Display this help and exit. 977 978<DT><SAMP>‘-V’</SAMP> 979<DD> 980<DT><SAMP>‘--version’</SAMP> 981<DD> 982<A NAME="IDX1143"></A> 983<A NAME="IDX1144"></A> 984Output version information and exit. 985 986<DT><SAMP>‘<VAR>textdomain</VAR>’</SAMP> 987<DD> 988Retrieve translated message from <VAR>textdomain</VAR>. 989 990<DT><SAMP>‘<VAR>msgid</VAR> <VAR>msgid-plural</VAR>’</SAMP> 991<DD> 992Translate <VAR>msgid</VAR> (English singular) / <VAR>msgid-plural</VAR> (English plural). 993 994<DT><SAMP>‘<VAR>count</VAR>’</SAMP> 995<DD> 996Choose singular/plural form based on this value. 997 998</DL> 999 1000<P> 1001If the <VAR>textdomain</VAR> parameter is not given, the domain is determined from 1002the environment variable <CODE>TEXTDOMAIN</CODE>. If the message catalog is not 1003found in the regular directory, another location can be specified with the 1004environment variable <CODE>TEXTDOMAINDIR</CODE>. 1005 1006</P> 1007 1008 1009<H4><A NAME="SEC261" HREF="gettext_toc.html#TOC261">15.5.2.5 Invoking the <CODE>envsubst</CODE> program</A></H4> 1010 1011<P> 1012<A NAME="IDX1145"></A> 1013<A NAME="IDX1146"></A> 1014 1015<PRE> 1016envsubst [<VAR>option</VAR>] [<VAR>shell-format</VAR>] 1017</PRE> 1018 1019<P> 1020<A NAME="IDX1147"></A> 1021<A NAME="IDX1148"></A> 1022<A NAME="IDX1149"></A> 1023The <CODE>envsubst</CODE> program substitutes the values of environment variables. 1024 1025</P> 1026<P> 1027<STRONG>Operation mode</STRONG> 1028 1029</P> 1030<DL COMPACT> 1031 1032<DT><SAMP>‘-v’</SAMP> 1033<DD> 1034<DT><SAMP>‘--variables’</SAMP> 1035<DD> 1036<A NAME="IDX1150"></A> 1037<A NAME="IDX1151"></A> 1038Output the variables occurring in <VAR>shell-format</VAR>. 1039 1040</DL> 1041 1042<P> 1043<STRONG>Informative output</STRONG> 1044 1045</P> 1046<DL COMPACT> 1047 1048<DT><SAMP>‘-h’</SAMP> 1049<DD> 1050<DT><SAMP>‘--help’</SAMP> 1051<DD> 1052<A NAME="IDX1152"></A> 1053<A NAME="IDX1153"></A> 1054Display this help and exit. 1055 1056<DT><SAMP>‘-V’</SAMP> 1057<DD> 1058<DT><SAMP>‘--version’</SAMP> 1059<DD> 1060<A NAME="IDX1154"></A> 1061<A NAME="IDX1155"></A> 1062Output version information and exit. 1063 1064</DL> 1065 1066<P> 1067In normal operation mode, standard input is copied to standard output, 1068with references to environment variables of the form <CODE>$VARIABLE</CODE> or 1069<CODE>${VARIABLE}</CODE> being replaced with the corresponding values. If a 1070<VAR>shell-format</VAR> is given, only those environment variables that are 1071referenced in <VAR>shell-format</VAR> are substituted; otherwise all environment 1072variables references occurring in standard input are substituted. 1073 1074</P> 1075<P> 1076These substitutions are a subset of the substitutions that a shell performs 1077on unquoted and double-quoted strings. Other kinds of substitutions done 1078by a shell, such as <CODE>${<VAR>variable</VAR>-<VAR>default</VAR>}</CODE> or 1079<CODE>$(<VAR>command-list</VAR>)</CODE> or <CODE>`<VAR>command-list</VAR>`</CODE>, are not performed 1080by the <CODE>envsubst</CODE> program, due to security reasons. 1081 1082</P> 1083<P> 1084When <CODE>--variables</CODE> is used, standard input is ignored, and the output 1085consists of the environment variables that are referenced in 1086<VAR>shell-format</VAR>, one per line. 1087 1088</P> 1089 1090 1091<H4><A NAME="SEC262" HREF="gettext_toc.html#TOC262">15.5.2.6 Invoking the <CODE>eval_gettext</CODE> function</A></H4> 1092 1093<P> 1094<A NAME="IDX1156"></A> 1095 1096<PRE> 1097eval_gettext <VAR>msgid</VAR> 1098</PRE> 1099 1100<P> 1101<A NAME="IDX1157"></A> 1102This function outputs the native language translation of a textual message, 1103performing dollar-substitution on the result. Note that only shell variables 1104mentioned in <VAR>msgid</VAR> will be dollar-substituted in the result. 1105 1106</P> 1107 1108 1109<H4><A NAME="SEC263" HREF="gettext_toc.html#TOC263">15.5.2.7 Invoking the <CODE>eval_ngettext</CODE> function</A></H4> 1110 1111<P> 1112<A NAME="IDX1158"></A> 1113 1114<PRE> 1115eval_ngettext <VAR>msgid</VAR> <VAR>msgid-plural</VAR> <VAR>count</VAR> 1116</PRE> 1117 1118<P> 1119<A NAME="IDX1159"></A> 1120This function outputs the native language translation of a textual message 1121whose grammatical form depends on a number, performing dollar-substitution 1122on the result. Note that only shell variables mentioned in <VAR>msgid</VAR> or 1123<VAR>msgid-plural</VAR> will be dollar-substituted in the result. 1124 1125</P> 1126 1127 1128<H3><A NAME="SEC264" HREF="gettext_toc.html#TOC264">15.5.3 bash - Bourne-Again Shell Script</A></H3> 1129<P> 1130<A NAME="IDX1160"></A> 1131 1132</P> 1133<P> 1134GNU <CODE>bash</CODE> 2.0 or newer has a special shorthand for translating a 1135string and substituting variable values in it: <CODE>$"msgid"</CODE>. But 1136the use of this construct is <STRONG>discouraged</STRONG>, due to the security 1137holes it opens and due to its portability problems. 1138 1139</P> 1140<P> 1141The security holes of <CODE>$"..."</CODE> come from the fact that after looking up 1142the translation of the string, <CODE>bash</CODE> processes it like it processes 1143any double-quoted string: dollar and backquote processing, like <SAMP>‘eval’</SAMP> 1144does. 1145 1146</P> 1147 1148<OL> 1149<LI> 1150 1151In a locale whose encoding is one of BIG5, BIG5-HKSCS, GBK, GB18030, SHIFT_JIS, 1152JOHAB, some double-byte characters have a second byte whose value is 1153<CODE>0x60</CODE>. For example, the byte sequence <CODE>\xe0\x60</CODE> is a single 1154character in these locales. Many versions of <CODE>bash</CODE> (all versions 1155up to bash-2.05, and newer versions on platforms without <CODE>mbsrtowcs()</CODE> 1156function) don't know about character boundaries and see a backquote character 1157where there is only a particular Chinese character. Thus it can start 1158executing part of the translation as a command list. This situation can occur 1159even without the translator being aware of it: if the translator provides 1160translations in the UTF-8 encoding, it is the <CODE>gettext()</CODE> function which 1161will, during its conversion from the translator's encoding to the user's 1162locale's encoding, produce the dangerous <CODE>\x60</CODE> bytes. 1163 1164<LI> 1165 1166A translator could - voluntarily or inadvertently - use backquotes 1167<CODE>"`...`"</CODE> or dollar-parentheses <CODE>"$(...)"</CODE> in her translations. 1168The enclosed strings would be executed as command lists by the shell. 1169</OL> 1170 1171<P> 1172The portability problem is that <CODE>bash</CODE> must be built with 1173internationalization support; this is normally not the case on systems 1174that don't have the <CODE>gettext()</CODE> function in libc. 1175 1176</P> 1177 1178 1179<H3><A NAME="SEC265" HREF="gettext_toc.html#TOC265">15.5.4 Python</A></H3> 1180<P> 1181<A NAME="IDX1161"></A> 1182 1183</P> 1184<DL COMPACT> 1185 1186<DT>RPMs 1187<DD> 1188python 1189 1190<DT>File extension 1191<DD> 1192<CODE>py</CODE> 1193 1194<DT>String syntax 1195<DD> 1196<CODE>'abc'</CODE>, <CODE>u'abc'</CODE>, <CODE>r'abc'</CODE>, <CODE>ur'abc'</CODE>, 1197<BR><CODE>"abc"</CODE>, <CODE>u"abc"</CODE>, <CODE>r"abc"</CODE>, <CODE>ur"abc"</CODE>, 1198<BR><CODE>”'abc”'</CODE>, <CODE>u”'abc”'</CODE>, <CODE>r”'abc”'</CODE>, <CODE>ur”'abc”'</CODE>, 1199<BR><CODE>"""abc"""</CODE>, <CODE>u"""abc"""</CODE>, <CODE>r"""abc"""</CODE>, <CODE>ur"""abc"""</CODE> 1200 1201<DT>gettext shorthand 1202<DD> 1203<CODE>_('abc')</CODE> etc. 1204 1205<DT>gettext/ngettext functions 1206<DD> 1207<CODE>gettext.gettext</CODE>, <CODE>gettext.dgettext</CODE>, 1208<CODE>gettext.ngettext</CODE>, <CODE>gettext.dngettext</CODE>, 1209also <CODE>ugettext</CODE>, <CODE>ungettext</CODE> 1210 1211<DT>textdomain 1212<DD> 1213<CODE>gettext.textdomain</CODE> function, or 1214<CODE>gettext.install(<VAR>domain</VAR>)</CODE> function 1215 1216<DT>bindtextdomain 1217<DD> 1218<CODE>gettext.bindtextdomain</CODE> function, or 1219<CODE>gettext.install(<VAR>domain</VAR>,<VAR>localedir</VAR>)</CODE> function 1220 1221<DT>setlocale 1222<DD> 1223not used by the gettext emulation 1224 1225<DT>Prerequisite 1226<DD> 1227<CODE>import gettext</CODE> 1228 1229<DT>Use or emulate GNU gettext 1230<DD> 1231emulate 1232 1233<DT>Extractor 1234<DD> 1235<CODE>xgettext</CODE> 1236 1237<DT>Formatting with positions 1238<DD> 1239<CODE>'...%(ident)d...' % { 'ident': value }</CODE> 1240 1241<DT>Portability 1242<DD> 1243fully portable 1244 1245<DT>po-mode marking 1246<DD> 1247--- 1248</DL> 1249 1250<P> 1251An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-python</CODE>. 1252 1253</P> 1254 1255 1256<H3><A NAME="SEC266" HREF="gettext_toc.html#TOC266">15.5.5 GNU clisp - Common Lisp</A></H3> 1257<P> 1258<A NAME="IDX1162"></A> 1259<A NAME="IDX1163"></A> 1260<A NAME="IDX1164"></A> 1261 1262</P> 1263<DL COMPACT> 1264 1265<DT>RPMs 1266<DD> 1267clisp 2.28 or newer 1268 1269<DT>File extension 1270<DD> 1271<CODE>lisp</CODE> 1272 1273<DT>String syntax 1274<DD> 1275<CODE>"abc"</CODE> 1276 1277<DT>gettext shorthand 1278<DD> 1279<CODE>(_ "abc")</CODE>, <CODE>(ENGLISH "abc")</CODE> 1280 1281<DT>gettext/ngettext functions 1282<DD> 1283<CODE>i18n:gettext</CODE>, <CODE>i18n:ngettext</CODE> 1284 1285<DT>textdomain 1286<DD> 1287<CODE>i18n:textdomain</CODE> 1288 1289<DT>bindtextdomain 1290<DD> 1291<CODE>i18n:textdomaindir</CODE> 1292 1293<DT>setlocale 1294<DD> 1295automatic 1296 1297<DT>Prerequisite 1298<DD> 1299--- 1300 1301<DT>Use or emulate GNU gettext 1302<DD> 1303use 1304 1305<DT>Extractor 1306<DD> 1307<CODE>xgettext -k_ -kENGLISH</CODE> 1308 1309<DT>Formatting with positions 1310<DD> 1311<CODE>format "~1@*~D ~0@*~D"</CODE> 1312 1313<DT>Portability 1314<DD> 1315On platforms without gettext, no translation. 1316 1317<DT>po-mode marking 1318<DD> 1319--- 1320</DL> 1321 1322<P> 1323An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-clisp</CODE>. 1324 1325</P> 1326 1327 1328<H3><A NAME="SEC267" HREF="gettext_toc.html#TOC267">15.5.6 GNU clisp C sources</A></H3> 1329<P> 1330<A NAME="IDX1165"></A> 1331 1332</P> 1333<DL COMPACT> 1334 1335<DT>RPMs 1336<DD> 1337clisp 1338 1339<DT>File extension 1340<DD> 1341<CODE>d</CODE> 1342 1343<DT>String syntax 1344<DD> 1345<CODE>"abc"</CODE> 1346 1347<DT>gettext shorthand 1348<DD> 1349<CODE>ENGLISH ? "abc" : ""</CODE> 1350<BR><CODE>GETTEXT("abc")</CODE> 1351<BR><CODE>GETTEXTL("abc")</CODE> 1352 1353<DT>gettext/ngettext functions 1354<DD> 1355<CODE>clgettext</CODE>, <CODE>clgettextl</CODE> 1356 1357<DT>textdomain 1358<DD> 1359--- 1360 1361<DT>bindtextdomain 1362<DD> 1363--- 1364 1365<DT>setlocale 1366<DD> 1367automatic 1368 1369<DT>Prerequisite 1370<DD> 1371<CODE>#include "lispbibl.c"</CODE> 1372 1373<DT>Use or emulate GNU gettext 1374<DD> 1375use 1376 1377<DT>Extractor 1378<DD> 1379<CODE>clisp-xgettext</CODE> 1380 1381<DT>Formatting with positions 1382<DD> 1383<CODE>fprintf "%2$d %1$d"</CODE> 1384 1385<DT>Portability 1386<DD> 1387On platforms without gettext, no translation. 1388 1389<DT>po-mode marking 1390<DD> 1391--- 1392</DL> 1393 1394 1395 1396<H3><A NAME="SEC268" HREF="gettext_toc.html#TOC268">15.5.7 Emacs Lisp</A></H3> 1397<P> 1398<A NAME="IDX1166"></A> 1399 1400</P> 1401<DL COMPACT> 1402 1403<DT>RPMs 1404<DD> 1405emacs, xemacs 1406 1407<DT>File extension 1408<DD> 1409<CODE>el</CODE> 1410 1411<DT>String syntax 1412<DD> 1413<CODE>"abc"</CODE> 1414 1415<DT>gettext shorthand 1416<DD> 1417<CODE>(_"abc")</CODE> 1418 1419<DT>gettext/ngettext functions 1420<DD> 1421<CODE>gettext</CODE>, <CODE>dgettext</CODE> (xemacs only) 1422 1423<DT>textdomain 1424<DD> 1425<CODE>domain</CODE> special form (xemacs only) 1426 1427<DT>bindtextdomain 1428<DD> 1429<CODE>bind-text-domain</CODE> function (xemacs only) 1430 1431<DT>setlocale 1432<DD> 1433automatic 1434 1435<DT>Prerequisite 1436<DD> 1437--- 1438 1439<DT>Use or emulate GNU gettext 1440<DD> 1441use 1442 1443<DT>Extractor 1444<DD> 1445<CODE>xgettext</CODE> 1446 1447<DT>Formatting with positions 1448<DD> 1449<CODE>format "%2$d %1$d"</CODE> 1450 1451<DT>Portability 1452<DD> 1453Only XEmacs. Without <CODE>I18N3</CODE> defined at build time, no translation. 1454 1455<DT>po-mode marking 1456<DD> 1457--- 1458</DL> 1459 1460 1461 1462<H3><A NAME="SEC269" HREF="gettext_toc.html#TOC269">15.5.8 librep</A></H3> 1463<P> 1464<A NAME="IDX1167"></A> 1465 1466</P> 1467<DL COMPACT> 1468 1469<DT>RPMs 1470<DD> 1471librep 0.15.3 or newer 1472 1473<DT>File extension 1474<DD> 1475<CODE>jl</CODE> 1476 1477<DT>String syntax 1478<DD> 1479<CODE>"abc"</CODE> 1480 1481<DT>gettext shorthand 1482<DD> 1483<CODE>(_"abc")</CODE> 1484 1485<DT>gettext/ngettext functions 1486<DD> 1487<CODE>gettext</CODE> 1488 1489<DT>textdomain 1490<DD> 1491<CODE>textdomain</CODE> function 1492 1493<DT>bindtextdomain 1494<DD> 1495<CODE>bindtextdomain</CODE> function 1496 1497<DT>setlocale 1498<DD> 1499--- 1500 1501<DT>Prerequisite 1502<DD> 1503<CODE>(require 'rep.i18n.gettext)</CODE> 1504 1505<DT>Use or emulate GNU gettext 1506<DD> 1507use 1508 1509<DT>Extractor 1510<DD> 1511<CODE>xgettext</CODE> 1512 1513<DT>Formatting with positions 1514<DD> 1515<CODE>format "%2$d %1$d"</CODE> 1516 1517<DT>Portability 1518<DD> 1519On platforms without gettext, no translation. 1520 1521<DT>po-mode marking 1522<DD> 1523--- 1524</DL> 1525 1526<P> 1527An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-librep</CODE>. 1528 1529</P> 1530 1531 1532<H3><A NAME="SEC270" HREF="gettext_toc.html#TOC270">15.5.9 GNU guile - Scheme</A></H3> 1533<P> 1534<A NAME="IDX1168"></A> 1535<A NAME="IDX1169"></A> 1536 1537</P> 1538<DL COMPACT> 1539 1540<DT>RPMs 1541<DD> 1542guile 1543 1544<DT>File extension 1545<DD> 1546<CODE>scm</CODE> 1547 1548<DT>String syntax 1549<DD> 1550<CODE>"abc"</CODE> 1551 1552<DT>gettext shorthand 1553<DD> 1554<CODE>(_ "abc")</CODE> 1555 1556<DT>gettext/ngettext functions 1557<DD> 1558<CODE>gettext</CODE>, <CODE>ngettext</CODE> 1559 1560<DT>textdomain 1561<DD> 1562<CODE>textdomain</CODE> 1563 1564<DT>bindtextdomain 1565<DD> 1566<CODE>bindtextdomain</CODE> 1567 1568<DT>setlocale 1569<DD> 1570<CODE>(catch #t (lambda () (setlocale LC_ALL "")) (lambda args #f))</CODE> 1571 1572<DT>Prerequisite 1573<DD> 1574<CODE>(use-modules (ice-9 format))</CODE> 1575 1576<DT>Use or emulate GNU gettext 1577<DD> 1578use 1579 1580<DT>Extractor 1581<DD> 1582<CODE>xgettext -k_</CODE> 1583 1584<DT>Formatting with positions 1585<DD> 1586--- 1587 1588<DT>Portability 1589<DD> 1590On platforms without gettext, no translation. 1591 1592<DT>po-mode marking 1593<DD> 1594--- 1595</DL> 1596 1597<P> 1598An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-guile</CODE>. 1599 1600</P> 1601 1602 1603<H3><A NAME="SEC271" HREF="gettext_toc.html#TOC271">15.5.10 GNU Smalltalk</A></H3> 1604<P> 1605<A NAME="IDX1170"></A> 1606 1607</P> 1608<DL COMPACT> 1609 1610<DT>RPMs 1611<DD> 1612smalltalk 1613 1614<DT>File extension 1615<DD> 1616<CODE>st</CODE> 1617 1618<DT>String syntax 1619<DD> 1620<CODE>'abc'</CODE> 1621 1622<DT>gettext shorthand 1623<DD> 1624<CODE>NLS ? 'abc'</CODE> 1625 1626<DT>gettext/ngettext functions 1627<DD> 1628<CODE>LcMessagesDomain>>#at:</CODE>, <CODE>LcMessagesDomain>>#at:plural:with:</CODE> 1629 1630<DT>textdomain 1631<DD> 1632<CODE>LcMessages>>#domain:localeDirectory:</CODE> (returns a <CODE>LcMessagesDomain</CODE> 1633object).<BR> 1634Example: <CODE>I18N Locale default messages domain: 'gettext' localeDirectory: /usr/local/share/locale'</CODE> 1635 1636<DT>bindtextdomain 1637<DD> 1638<CODE>LcMessages>>#domain:localeDirectory:</CODE>, see above. 1639 1640<DT>setlocale 1641<DD> 1642Automatic if you use <CODE>I18N Locale default</CODE>. 1643 1644<DT>Prerequisite 1645<DD> 1646<CODE>PackageLoader fileInPackage: 'I18N'!</CODE> 1647 1648<DT>Use or emulate GNU gettext 1649<DD> 1650emulate 1651 1652<DT>Extractor 1653<DD> 1654<CODE>xgettext</CODE> 1655 1656<DT>Formatting with positions 1657<DD> 1658<CODE>'%1 %2' bindWith: 'Hello' with: 'world'</CODE> 1659 1660<DT>Portability 1661<DD> 1662fully portable 1663 1664<DT>po-mode marking 1665<DD> 1666--- 1667</DL> 1668 1669<P> 1670An example is available in the <TT>‘examples’</TT> directory: 1671<CODE>hello-smalltalk</CODE>. 1672 1673</P> 1674 1675 1676<H3><A NAME="SEC272" HREF="gettext_toc.html#TOC272">15.5.11 Java</A></H3> 1677<P> 1678<A NAME="IDX1171"></A> 1679 1680</P> 1681<DL COMPACT> 1682 1683<DT>RPMs 1684<DD> 1685java, java2 1686 1687<DT>File extension 1688<DD> 1689<CODE>java</CODE> 1690 1691<DT>String syntax 1692<DD> 1693"abc" 1694 1695<DT>gettext shorthand 1696<DD> 1697_("abc") 1698 1699<DT>gettext/ngettext functions 1700<DD> 1701<CODE>GettextResource.gettext</CODE>, <CODE>GettextResource.ngettext</CODE> 1702 1703<DT>textdomain 1704<DD> 1705---, use <CODE>ResourceBundle.getResource</CODE> instead 1706 1707<DT>bindtextdomain 1708<DD> 1709---, use CLASSPATH instead 1710 1711<DT>setlocale 1712<DD> 1713automatic 1714 1715<DT>Prerequisite 1716<DD> 1717--- 1718 1719<DT>Use or emulate GNU gettext 1720<DD> 1721---, uses a Java specific message catalog format 1722 1723<DT>Extractor 1724<DD> 1725<CODE>xgettext -k_</CODE> 1726 1727<DT>Formatting with positions 1728<DD> 1729<CODE>MessageFormat.format "{1,number} {0,number}"</CODE> 1730 1731<DT>Portability 1732<DD> 1733fully portable 1734 1735<DT>po-mode marking 1736<DD> 1737--- 1738</DL> 1739 1740<P> 1741Before marking strings as internationalizable, uses of the string 1742concatenation operator need to be converted to <CODE>MessageFormat</CODE> 1743applications. For example, <CODE>"file "+filename+" not found"</CODE> becomes 1744<CODE>MessageFormat.format("file {0} not found", new Object[] { filename })</CODE>. 1745Only after this is done, can the strings be marked and extracted. 1746 1747</P> 1748<P> 1749GNU gettext uses the native Java internationalization mechanism, namely 1750<CODE>ResourceBundle</CODE>s. There are two formats of <CODE>ResourceBundle</CODE>s: 1751<CODE>.properties</CODE> files and <CODE>.class</CODE> files. The <CODE>.properties</CODE> 1752format is a text file which the translators can directly edit, like PO 1753files, but which doesn't support plural forms. Whereas the <CODE>.class</CODE> 1754format is compiled from <CODE>.java</CODE> source code and can support plural 1755forms (provided it is accessed through an appropriate API, see below). 1756 1757</P> 1758<P> 1759To convert a PO file to a <CODE>.properties</CODE> file, the <CODE>msgcat</CODE> 1760program can be used with the option <CODE>--properties-output</CODE>. To convert 1761a <CODE>.properties</CODE> file back to a PO file, the <CODE>msgcat</CODE> program 1762can be used with the option <CODE>--properties-input</CODE>. All the tools 1763that manipulate PO files can work with <CODE>.properties</CODE> files as well, 1764if given the <CODE>--properties-input</CODE> and/or <CODE>--properties-output</CODE> 1765option. 1766 1767</P> 1768<P> 1769To convert a PO file to a ResourceBundle class, the <CODE>msgfmt</CODE> program 1770can be used with the option <CODE>--java</CODE> or <CODE>--java2</CODE>. To convert a 1771ResourceBundle back to a PO file, the <CODE>msgunfmt</CODE> program can be used 1772with the option <CODE>--java</CODE>. 1773 1774</P> 1775<P> 1776Two different programmatic APIs can be used to access ResourceBundles. 1777Note that both APIs work with all kinds of ResourceBundles, whether 1778GNU gettext generated classes, or other <CODE>.class</CODE> or <CODE>.properties</CODE> 1779files. 1780 1781</P> 1782 1783<OL> 1784<LI> 1785 1786The <CODE>java.util.ResourceBundle</CODE> API. 1787 1788In particular, its <CODE>getString</CODE> function returns a string translation. 1789Note that a missing translation yields a <CODE>MissingResourceException</CODE>. 1790 1791This has the advantage of being the standard API. And it does not require 1792any additional libraries, only the <CODE>msgcat</CODE> generated <CODE>.properties</CODE> 1793files or the <CODE>msgfmt</CODE> generated <CODE>.class</CODE> files. But it cannot do 1794plural handling, even if the resource was generated by <CODE>msgfmt</CODE> from 1795a PO file with plural handling. 1796 1797<LI> 1798 1799The <CODE>gnu.gettext.GettextResource</CODE> API. 1800 1801Reference documentation in Javadoc 1.1 style format 1802is in the <A HREF="javadoc1/tree.html">javadoc1 directory</A> and 1803in Javadoc 2 style format 1804in the <A HREF="javadoc2/index.html">javadoc2 directory</A>. 1805 1806Its <CODE>gettext</CODE> function returns a string translation. Note that when 1807a translation is missing, the <VAR>msgid</VAR> argument is returned unchanged. 1808 1809This has the advantage of having the <CODE>ngettext</CODE> function for plural 1810handling. 1811 1812<A NAME="IDX1172"></A> 1813To use this API, one needs the <CODE>libintl.jar</CODE> file which is part of 1814the GNU gettext package and distributed under the LGPL. 1815</OL> 1816 1817<P> 1818Three examples, using the second API, are available in the <TT>‘examples’</TT> 1819directory: <CODE>hello-java</CODE>, <CODE>hello-java-awt</CODE>, <CODE>hello-java-swing</CODE>. 1820 1821</P> 1822<P> 1823Now, to make use of the API and define a shorthand for <SAMP>‘getString’</SAMP>, 1824there are three idioms that you can choose from: 1825 1826</P> 1827 1828<UL> 1829<LI> 1830 1831(This one assumes Java 1.5 or newer.) 1832In a unique class of your project, say <SAMP>‘Util’</SAMP>, define a static variable 1833holding the <CODE>ResourceBundle</CODE> instance and the shorthand: 1834 1835 1836<PRE> 1837private static ResourceBundle myResources = 1838 ResourceBundle.getBundle("domain-name"); 1839public static String _(String s) { 1840 return myResources.getString(s); 1841} 1842</PRE> 1843 1844All classes containing internationalized strings then contain 1845 1846 1847<PRE> 1848import static Util._; 1849</PRE> 1850 1851and the shorthand is used like this: 1852 1853 1854<PRE> 1855System.out.println(_("Operation completed.")); 1856</PRE> 1857 1858<LI> 1859 1860In a unique class of your project, say <SAMP>‘Util’</SAMP>, define a static variable 1861holding the <CODE>ResourceBundle</CODE> instance: 1862 1863 1864<PRE> 1865public static ResourceBundle myResources = 1866 ResourceBundle.getBundle("domain-name"); 1867</PRE> 1868 1869All classes containing internationalized strings then contain 1870 1871 1872<PRE> 1873private static ResourceBundle res = Util.myResources; 1874private static String _(String s) { return res.getString(s); } 1875</PRE> 1876 1877and the shorthand is used like this: 1878 1879 1880<PRE> 1881System.out.println(_("Operation completed.")); 1882</PRE> 1883 1884<LI> 1885 1886You add a class with a very short name, say <SAMP>‘S’</SAMP>, containing just the 1887definition of the resource bundle and of the shorthand: 1888 1889 1890<PRE> 1891public class S { 1892 public static ResourceBundle myResources = 1893 ResourceBundle.getBundle("domain-name"); 1894 public static String _(String s) { 1895 return myResources.getString(s); 1896 } 1897} 1898</PRE> 1899 1900and the shorthand is used like this: 1901 1902 1903<PRE> 1904System.out.println(S._("Operation completed.")); 1905</PRE> 1906 1907</UL> 1908 1909<P> 1910Which of the three idioms you choose, will depend on whether your project 1911requires portability to Java versions prior to Java 1.5 and, if so, whether 1912copying two lines of codes into every class is more acceptable in your project 1913than a class with a single-letter name. 1914 1915</P> 1916 1917 1918<H3><A NAME="SEC273" HREF="gettext_toc.html#TOC273">15.5.12 C#</A></H3> 1919<P> 1920<A NAME="IDX1173"></A> 1921 1922</P> 1923<DL COMPACT> 1924 1925<DT>RPMs 1926<DD> 1927pnet, pnetlib 0.6.2 or newer, or mono 0.29 or newer 1928 1929<DT>File extension 1930<DD> 1931<CODE>cs</CODE> 1932 1933<DT>String syntax 1934<DD> 1935<CODE>"abc"</CODE>, <CODE>@"abc"</CODE> 1936 1937<DT>gettext shorthand 1938<DD> 1939_("abc") 1940 1941<DT>gettext/ngettext functions 1942<DD> 1943<CODE>GettextResourceManager.GetString</CODE>, 1944<CODE>GettextResourceManager.GetPluralString</CODE> 1945 1946<DT>textdomain 1947<DD> 1948<CODE>new GettextResourceManager(domain)</CODE> 1949 1950<DT>bindtextdomain 1951<DD> 1952---, compiled message catalogs are located in subdirectories of the directory 1953containing the executable 1954 1955<DT>setlocale 1956<DD> 1957automatic 1958 1959<DT>Prerequisite 1960<DD> 1961--- 1962 1963<DT>Use or emulate GNU gettext 1964<DD> 1965---, uses a C# specific message catalog format 1966 1967<DT>Extractor 1968<DD> 1969<CODE>xgettext -k_</CODE> 1970 1971<DT>Formatting with positions 1972<DD> 1973<CODE>String.Format "{1} {0}"</CODE> 1974 1975<DT>Portability 1976<DD> 1977fully portable 1978 1979<DT>po-mode marking 1980<DD> 1981--- 1982</DL> 1983 1984<P> 1985Before marking strings as internationalizable, uses of the string 1986concatenation operator need to be converted to <CODE>String.Format</CODE> 1987invocations. For example, <CODE>"file "+filename+" not found"</CODE> becomes 1988<CODE>String.Format("file {0} not found", filename)</CODE>. 1989Only after this is done, can the strings be marked and extracted. 1990 1991</P> 1992<P> 1993GNU gettext uses the native C#/.NET internationalization mechanism, namely 1994the classes <CODE>ResourceManager</CODE> and <CODE>ResourceSet</CODE>. Applications 1995use the <CODE>ResourceManager</CODE> methods to retrieve the native language 1996translation of strings. An instance of <CODE>ResourceSet</CODE> is the in-memory 1997representation of a message catalog file. The <CODE>ResourceManager</CODE> loads 1998and accesses <CODE>ResourceSet</CODE> instances as needed to look up the 1999translations. 2000 2001</P> 2002<P> 2003There are two formats of <CODE>ResourceSet</CODE>s that can be directly loaded by 2004the C# runtime: <CODE>.resources</CODE> files and <CODE>.dll</CODE> files. 2005 2006</P> 2007 2008<UL> 2009<LI> 2010 2011The <CODE>.resources</CODE> format is a binary file usually generated through the 2012<CODE>resgen</CODE> or <CODE>monoresgen</CODE> utility, but which doesn't support plural 2013forms. <CODE>.resources</CODE> files can also be embedded in .NET <CODE>.exe</CODE> files. 2014This only affects whether a file system access is performed to load the message 2015catalog; it doesn't affect the contents of the message catalog. 2016 2017<LI> 2018 2019On the other hand, the <CODE>.dll</CODE> format is a binary file that is compiled 2020from <CODE>.cs</CODE> source code and can support plural forms (provided it is 2021accessed through the GNU gettext API, see below). 2022</UL> 2023 2024<P> 2025Note that these .NET <CODE>.dll</CODE> and <CODE>.exe</CODE> files are not tied to a 2026particular platform; their file format and GNU gettext for C# can be used 2027on any platform. 2028 2029</P> 2030<P> 2031To convert a PO file to a <CODE>.resources</CODE> file, the <CODE>msgfmt</CODE> program 2032can be used with the option <SAMP>‘--csharp-resources’</SAMP>. To convert a 2033<CODE>.resources</CODE> file back to a PO file, the <CODE>msgunfmt</CODE> program can be 2034used with the option <SAMP>‘--csharp-resources’</SAMP>. You can also, in some cases, 2035use the <CODE>resgen</CODE> program (from the <CODE>pnet</CODE> package) or the 2036<CODE>monoresgen</CODE> program (from the <CODE>mono</CODE>/<CODE>mcs</CODE> package). These 2037programs can also convert a <CODE>.resources</CODE> file back to a PO file. But 2038beware: as of this writing (January 2004), the <CODE>monoresgen</CODE> converter is 2039quite buggy and the <CODE>resgen</CODE> converter ignores the encoding of the PO 2040files. 2041 2042</P> 2043<P> 2044To convert a PO file to a <CODE>.dll</CODE> file, the <CODE>msgfmt</CODE> program can be 2045used with the option <CODE>--csharp</CODE>. The result will be a <CODE>.dll</CODE> file 2046containing a subclass of <CODE>GettextResourceSet</CODE>, which itself is a subclass 2047of <CODE>ResourceSet</CODE>. To convert a <CODE>.dll</CODE> file containing a 2048<CODE>GettextResourceSet</CODE> subclass back to a PO file, the <CODE>msgunfmt</CODE> 2049program can be used with the option <CODE>--csharp</CODE>. 2050 2051</P> 2052<P> 2053The advantages of the <CODE>.dll</CODE> format over the <CODE>.resources</CODE> format 2054are: 2055 2056</P> 2057 2058<OL> 2059<LI> 2060 2061Freedom to localize: Users can add their own translations to an application 2062after it has been built and distributed. Whereas when the programmer uses 2063a <CODE>ResourceManager</CODE> constructor provided by the system, the set of 2064<CODE>.resources</CODE> files for an application must be specified when the 2065application is built and cannot be extended afterwards. 2066 2067<LI> 2068 2069Plural handling: A message catalog in <CODE>.dll</CODE> format supports the plural 2070handling function <CODE>GetPluralString</CODE>. Whereas <CODE>.resources</CODE> files can 2071only contain data and only support lookups that depend on a single string. 2072 2073<LI> 2074 2075The <CODE>GettextResourceManager</CODE> that loads the message catalogs in 2076<CODE>.dll</CODE> format also provides for inheritance on a per-message basis. 2077For example, in Austrian (<CODE>de_AT</CODE>) locale, translations from the German 2078(<CODE>de</CODE>) message catalog will be used for messages not found in the 2079Austrian message catalog. This has the consequence that the Austrian 2080translators need only translate those few messages for which the translation 2081into Austrian differs from the German one. Whereas when working with 2082<CODE>.resources</CODE> files, each message catalog must provide the translations 2083of all messages by itself. 2084 2085<LI> 2086 2087The <CODE>GettextResourceManager</CODE> that loads the message catalogs in 2088<CODE>.dll</CODE> format also provides for a fallback: The English <VAR>msgid</VAR> is 2089returned when no translation can be found. Whereas when working with 2090<CODE>.resources</CODE> files, a language-neutral <CODE>.resources</CODE> file must 2091explicitly be provided as a fallback. 2092</OL> 2093 2094<P> 2095On the side of the programmatic APIs, the programmer can use either the 2096standard <CODE>ResourceManager</CODE> API and the GNU <CODE>GettextResourceManager</CODE> 2097API. The latter is an extension of the former, because 2098<CODE>GettextResourceManager</CODE> is a subclass of <CODE>ResourceManager</CODE>. 2099 2100</P> 2101 2102<OL> 2103<LI> 2104 2105The <CODE>System.Resources.ResourceManager</CODE> API. 2106 2107This API works with resources in <CODE>.resources</CODE> format. 2108 2109The creation of the <CODE>ResourceManager</CODE> is done through 2110 2111<PRE> 2112 new ResourceManager(domainname, Assembly.GetExecutingAssembly()) 2113</PRE> 2114 2115 2116The <CODE>GetString</CODE> function returns a string's translation. Note that this 2117function returns null when a translation is missing (i.e. not even found in 2118the fallback resource file). 2119 2120<LI> 2121 2122The <CODE>GNU.Gettext.GettextResourceManager</CODE> API. 2123 2124This API works with resources in <CODE>.dll</CODE> format. 2125 2126Reference documentation is in the 2127<A HREF="csharpdoc/index.html">csharpdoc directory</A>. 2128 2129The creation of the <CODE>ResourceManager</CODE> is done through 2130 2131<PRE> 2132 new GettextResourceManager(domainname) 2133</PRE> 2134 2135The <CODE>GetString</CODE> function returns a string's translation. Note that when 2136a translation is missing, the <VAR>msgid</VAR> argument is returned unchanged. 2137 2138The <CODE>GetPluralString</CODE> function returns a string translation with plural 2139handling, like the <CODE>ngettext</CODE> function in C. 2140 2141<A NAME="IDX1174"></A> 2142To use this API, one needs the <CODE>GNU.Gettext.dll</CODE> file which is part of 2143the GNU gettext package and distributed under the LGPL. 2144</OL> 2145 2146<P> 2147You can also mix both approaches: use the 2148<CODE>GNU.Gettext.GettextResourceManager</CODE> constructor, but otherwise use 2149only the <CODE>ResourceManager</CODE> type and only the <CODE>GetString</CODE> method. 2150This is appropriate when you want to profit from the tools for PO files, 2151but don't want to change an existing source code that uses 2152<CODE>ResourceManager</CODE> and don't (yet) need the <CODE>GetPluralString</CODE> method. 2153 2154</P> 2155<P> 2156Two examples, using the second API, are available in the <TT>‘examples’</TT> 2157directory: <CODE>hello-csharp</CODE>, <CODE>hello-csharp-forms</CODE>. 2158 2159</P> 2160<P> 2161Now, to make use of the API and define a shorthand for <SAMP>‘GetString’</SAMP>, 2162there are two idioms that you can choose from: 2163 2164</P> 2165 2166<UL> 2167<LI> 2168 2169In a unique class of your project, say <SAMP>‘Util’</SAMP>, define a static variable 2170holding the <CODE>ResourceManager</CODE> instance: 2171 2172 2173<PRE> 2174public static GettextResourceManager MyResourceManager = 2175 new GettextResourceManager("domain-name"); 2176</PRE> 2177 2178All classes containing internationalized strings then contain 2179 2180 2181<PRE> 2182private static GettextResourceManager Res = Util.MyResourceManager; 2183private static String _(String s) { return Res.GetString(s); } 2184</PRE> 2185 2186and the shorthand is used like this: 2187 2188 2189<PRE> 2190Console.WriteLine(_("Operation completed.")); 2191</PRE> 2192 2193<LI> 2194 2195You add a class with a very short name, say <SAMP>‘S’</SAMP>, containing just the 2196definition of the resource manager and of the shorthand: 2197 2198 2199<PRE> 2200public class S { 2201 public static GettextResourceManager MyResourceManager = 2202 new GettextResourceManager("domain-name"); 2203 public static String _(String s) { 2204 return MyResourceManager.GetString(s); 2205 } 2206} 2207</PRE> 2208 2209and the shorthand is used like this: 2210 2211 2212<PRE> 2213Console.WriteLine(S._("Operation completed.")); 2214</PRE> 2215 2216</UL> 2217 2218<P> 2219Which of the two idioms you choose, will depend on whether copying two lines 2220of codes into every class is more acceptable in your project than a class 2221with a single-letter name. 2222 2223</P> 2224 2225 2226<H3><A NAME="SEC274" HREF="gettext_toc.html#TOC274">15.5.13 GNU awk</A></H3> 2227<P> 2228<A NAME="IDX1175"></A> 2229<A NAME="IDX1176"></A> 2230 2231</P> 2232<DL COMPACT> 2233 2234<DT>RPMs 2235<DD> 2236gawk 3.1 or newer 2237 2238<DT>File extension 2239<DD> 2240<CODE>awk</CODE> 2241 2242<DT>String syntax 2243<DD> 2244<CODE>"abc"</CODE> 2245 2246<DT>gettext shorthand 2247<DD> 2248<CODE>_"abc"</CODE> 2249 2250<DT>gettext/ngettext functions 2251<DD> 2252<CODE>dcgettext</CODE>, missing <CODE>dcngettext</CODE> in gawk-3.1.0 2253 2254<DT>textdomain 2255<DD> 2256<CODE>TEXTDOMAIN</CODE> variable 2257 2258<DT>bindtextdomain 2259<DD> 2260<CODE>bindtextdomain</CODE> function 2261 2262<DT>setlocale 2263<DD> 2264automatic, but missing <CODE>setlocale (LC_MESSAGES, "")</CODE> in gawk-3.1.0 2265 2266<DT>Prerequisite 2267<DD> 2268--- 2269 2270<DT>Use or emulate GNU gettext 2271<DD> 2272use 2273 2274<DT>Extractor 2275<DD> 2276<CODE>xgettext</CODE> 2277 2278<DT>Formatting with positions 2279<DD> 2280<CODE>printf "%2$d %1$d"</CODE> (GNU awk only) 2281 2282<DT>Portability 2283<DD> 2284On platforms without gettext, no translation. On non-GNU awks, you must 2285define <CODE>dcgettext</CODE>, <CODE>dcngettext</CODE> and <CODE>bindtextdomain</CODE> 2286yourself. 2287 2288<DT>po-mode marking 2289<DD> 2290--- 2291</DL> 2292 2293<P> 2294An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-gawk</CODE>. 2295 2296</P> 2297 2298 2299<H3><A NAME="SEC275" HREF="gettext_toc.html#TOC275">15.5.14 Pascal - Free Pascal Compiler</A></H3> 2300<P> 2301<A NAME="IDX1177"></A> 2302<A NAME="IDX1178"></A> 2303<A NAME="IDX1179"></A> 2304 2305</P> 2306<DL COMPACT> 2307 2308<DT>RPMs 2309<DD> 2310fpk 2311 2312<DT>File extension 2313<DD> 2314<CODE>pp</CODE>, <CODE>pas</CODE> 2315 2316<DT>String syntax 2317<DD> 2318<CODE>'abc'</CODE> 2319 2320<DT>gettext shorthand 2321<DD> 2322automatic 2323 2324<DT>gettext/ngettext functions 2325<DD> 2326---, use <CODE>ResourceString</CODE> data type instead 2327 2328<DT>textdomain 2329<DD> 2330---, use <CODE>TranslateResourceStrings</CODE> function instead 2331 2332<DT>bindtextdomain 2333<DD> 2334---, use <CODE>TranslateResourceStrings</CODE> function instead 2335 2336<DT>setlocale 2337<DD> 2338automatic, but uses only LANG, not LC_MESSAGES or LC_ALL 2339 2340<DT>Prerequisite 2341<DD> 2342<CODE>{$mode delphi}</CODE> or <CODE>{$mode objfpc}</CODE><BR><CODE>uses gettext;</CODE> 2343 2344<DT>Use or emulate GNU gettext 2345<DD> 2346emulate partially 2347 2348<DT>Extractor 2349<DD> 2350<CODE>ppc386</CODE> followed by <CODE>xgettext</CODE> or <CODE>rstconv</CODE> 2351 2352<DT>Formatting with positions 2353<DD> 2354<CODE>uses sysutils;</CODE><BR><CODE>format "%1:d %0:d"</CODE> 2355 2356<DT>Portability 2357<DD> 2358? 2359 2360<DT>po-mode marking 2361<DD> 2362--- 2363</DL> 2364 2365<P> 2366The Pascal compiler has special support for the <CODE>ResourceString</CODE> data 2367type. It generates a <CODE>.rst</CODE> file. This is then converted to a 2368<CODE>.pot</CODE> file by use of <CODE>xgettext</CODE> or <CODE>rstconv</CODE>. At runtime, 2369a <CODE>.mo</CODE> file corresponding to translations of this <CODE>.pot</CODE> file 2370can be loaded using the <CODE>TranslateResourceStrings</CODE> function in the 2371<CODE>gettext</CODE> unit. 2372 2373</P> 2374<P> 2375An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-pascal</CODE>. 2376 2377</P> 2378 2379 2380<H3><A NAME="SEC276" HREF="gettext_toc.html#TOC276">15.5.15 wxWidgets library</A></H3> 2381<P> 2382<A NAME="IDX1180"></A> 2383 2384</P> 2385<DL COMPACT> 2386 2387<DT>RPMs 2388<DD> 2389wxGTK, gettext 2390 2391<DT>File extension 2392<DD> 2393<CODE>cpp</CODE> 2394 2395<DT>String syntax 2396<DD> 2397<CODE>"abc"</CODE> 2398 2399<DT>gettext shorthand 2400<DD> 2401<CODE>_("abc")</CODE> 2402 2403<DT>gettext/ngettext functions 2404<DD> 2405<CODE>wxLocale::GetString</CODE>, <CODE>wxGetTranslation</CODE> 2406 2407<DT>textdomain 2408<DD> 2409<CODE>wxLocale::AddCatalog</CODE> 2410 2411<DT>bindtextdomain 2412<DD> 2413<CODE>wxLocale::AddCatalogLookupPathPrefix</CODE> 2414 2415<DT>setlocale 2416<DD> 2417<CODE>wxLocale::Init</CODE>, <CODE>wxSetLocale</CODE> 2418 2419<DT>Prerequisite 2420<DD> 2421<CODE>#include <wx/intl.h></CODE> 2422 2423<DT>Use or emulate GNU gettext 2424<DD> 2425emulate, see <CODE>include/wx/intl.h</CODE> and <CODE>src/common/intl.cpp</CODE> 2426 2427<DT>Extractor 2428<DD> 2429<CODE>xgettext</CODE> 2430 2431<DT>Formatting with positions 2432<DD> 2433wxString::Format supports positions if and only if the system has 2434<CODE>wprintf()</CODE>, <CODE>vswprintf()</CODE> functions and they support positions 2435according to POSIX. 2436 2437<DT>Portability 2438<DD> 2439fully portable 2440 2441<DT>po-mode marking 2442<DD> 2443yes 2444</DL> 2445 2446 2447 2448<H3><A NAME="SEC277" HREF="gettext_toc.html#TOC277">15.5.16 YCP - YaST2 scripting language</A></H3> 2449<P> 2450<A NAME="IDX1181"></A> 2451<A NAME="IDX1182"></A> 2452 2453</P> 2454<DL COMPACT> 2455 2456<DT>RPMs 2457<DD> 2458libycp, libycp-devel, yast2-core, yast2-core-devel 2459 2460<DT>File extension 2461<DD> 2462<CODE>ycp</CODE> 2463 2464<DT>String syntax 2465<DD> 2466<CODE>"abc"</CODE> 2467 2468<DT>gettext shorthand 2469<DD> 2470<CODE>_("abc")</CODE> 2471 2472<DT>gettext/ngettext functions 2473<DD> 2474<CODE>_()</CODE> with 1 or 3 arguments 2475 2476<DT>textdomain 2477<DD> 2478<CODE>textdomain</CODE> statement 2479 2480<DT>bindtextdomain 2481<DD> 2482--- 2483 2484<DT>setlocale 2485<DD> 2486--- 2487 2488<DT>Prerequisite 2489<DD> 2490--- 2491 2492<DT>Use or emulate GNU gettext 2493<DD> 2494use 2495 2496<DT>Extractor 2497<DD> 2498<CODE>xgettext</CODE> 2499 2500<DT>Formatting with positions 2501<DD> 2502<CODE>sformat "%2 %1"</CODE> 2503 2504<DT>Portability 2505<DD> 2506fully portable 2507 2508<DT>po-mode marking 2509<DD> 2510--- 2511</DL> 2512 2513<P> 2514An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-ycp</CODE>. 2515 2516</P> 2517 2518 2519<H3><A NAME="SEC278" HREF="gettext_toc.html#TOC278">15.5.17 Tcl - Tk's scripting language</A></H3> 2520<P> 2521<A NAME="IDX1183"></A> 2522<A NAME="IDX1184"></A> 2523 2524</P> 2525<DL COMPACT> 2526 2527<DT>RPMs 2528<DD> 2529tcl 2530 2531<DT>File extension 2532<DD> 2533<CODE>tcl</CODE> 2534 2535<DT>String syntax 2536<DD> 2537<CODE>"abc"</CODE> 2538 2539<DT>gettext shorthand 2540<DD> 2541<CODE>[_ "abc"]</CODE> 2542 2543<DT>gettext/ngettext functions 2544<DD> 2545<CODE>::msgcat::mc</CODE> 2546 2547<DT>textdomain 2548<DD> 2549--- 2550 2551<DT>bindtextdomain 2552<DD> 2553---, use <CODE>::msgcat::mcload</CODE> instead 2554 2555<DT>setlocale 2556<DD> 2557automatic, uses LANG, but ignores LC_MESSAGES and LC_ALL 2558 2559<DT>Prerequisite 2560<DD> 2561<CODE>package require msgcat</CODE> 2562<BR><CODE>proc _ {s} {return [::msgcat::mc $s]}</CODE> 2563 2564<DT>Use or emulate GNU gettext 2565<DD> 2566---, uses a Tcl specific message catalog format 2567 2568<DT>Extractor 2569<DD> 2570<CODE>xgettext -k_</CODE> 2571 2572<DT>Formatting with positions 2573<DD> 2574<CODE>format "%2\$d %1\$d"</CODE> 2575 2576<DT>Portability 2577<DD> 2578fully portable 2579 2580<DT>po-mode marking 2581<DD> 2582--- 2583</DL> 2584 2585<P> 2586Two examples are available in the <TT>‘examples’</TT> directory: 2587<CODE>hello-tcl</CODE>, <CODE>hello-tcl-tk</CODE>. 2588 2589</P> 2590<P> 2591Before marking strings as internationalizable, substitutions of variables 2592into the string need to be converted to <CODE>format</CODE> applications. For 2593example, <CODE>"file $filename not found"</CODE> becomes 2594<CODE>[format "file %s not found" $filename]</CODE>. 2595Only after this is done, can the strings be marked and extracted. 2596After marking, this example becomes 2597<CODE>[format [_ "file %s not found"] $filename]</CODE> or 2598<CODE>[msgcat::mc "file %s not found" $filename]</CODE>. Note that the 2599<CODE>msgcat::mc</CODE> function implicitly calls <CODE>format</CODE> when more than one 2600argument is given. 2601 2602</P> 2603 2604 2605<H3><A NAME="SEC279" HREF="gettext_toc.html#TOC279">15.5.18 Perl</A></H3> 2606<P> 2607<A NAME="IDX1185"></A> 2608 2609</P> 2610<DL COMPACT> 2611 2612<DT>RPMs 2613<DD> 2614perl 2615 2616<DT>File extension 2617<DD> 2618<CODE>pl</CODE>, <CODE>PL</CODE>, <CODE>pm</CODE>, <CODE>cgi</CODE> 2619 2620<DT>String syntax 2621<DD> 2622 2623<UL> 2624 2625<LI><CODE>"abc"</CODE> 2626 2627<LI><CODE>'abc'</CODE> 2628 2629<LI><CODE>qq (abc)</CODE> 2630 2631<LI><CODE>q (abc)</CODE> 2632 2633<LI><CODE>qr /abc/</CODE> 2634 2635<LI><CODE>qx (/bin/date)</CODE> 2636 2637<LI><CODE>/pattern match/</CODE> 2638 2639<LI><CODE>?pattern match?</CODE> 2640 2641<LI><CODE>s/substitution/operators/</CODE> 2642 2643<LI><CODE>$tied_hash{"message"}</CODE> 2644 2645<LI><CODE>$tied_hash_reference->{"message"}</CODE> 2646 2647<LI>etc., issue the command <SAMP>‘man perlsyn’</SAMP> for details 2648 2649</UL> 2650 2651<DT>gettext shorthand 2652<DD> 2653<CODE>__</CODE> (double underscore) 2654 2655<DT>gettext/ngettext functions 2656<DD> 2657<CODE>gettext</CODE>, <CODE>dgettext</CODE>, <CODE>dcgettext</CODE>, <CODE>ngettext</CODE>, 2658<CODE>dngettext</CODE>, <CODE>dcngettext</CODE> 2659 2660<DT>textdomain 2661<DD> 2662<CODE>textdomain</CODE> function 2663 2664<DT>bindtextdomain 2665<DD> 2666<CODE>bindtextdomain</CODE> function 2667 2668<DT>bind_textdomain_codeset 2669<DD> 2670<CODE>bind_textdomain_codeset</CODE> function 2671 2672<DT>setlocale 2673<DD> 2674Use <CODE>setlocale (LC_ALL, "");</CODE> 2675 2676<DT>Prerequisite 2677<DD> 2678<CODE>use POSIX;</CODE> 2679<BR><CODE>use Locale::TextDomain;</CODE> (included in the package libintl-perl 2680which is available on the Comprehensive Perl Archive Network CPAN, 2681http://www.cpan.org/). 2682 2683<DT>Use or emulate GNU gettext 2684<DD> 2685platform dependent: gettext_pp emulates, gettext_xs uses GNU gettext 2686 2687<DT>Extractor 2688<DD> 2689<CODE>xgettext -k__ -k\$__ -k%__ -k__x -k__n:1,2 -k__nx:1,2 -k__xn:1,2 -kN__ -k</CODE> 2690 2691<DT>Formatting with positions 2692<DD> 2693Both kinds of format strings support formatting with positions. 2694<BR><CODE>printf "%2\$d %1\$d", ...</CODE> (requires Perl 5.8.0 or newer) 2695<BR><CODE>__expand("[new] replaces [old]", old => $oldvalue, new => $newvalue)</CODE> 2696 2697<DT>Portability 2698<DD> 2699The <CODE>libintl-perl</CODE> package is platform independent but is not 2700part of the Perl core. The programmer is responsible for 2701providing a dummy implementation of the required functions if the 2702package is not installed on the target system. 2703 2704<DT>po-mode marking 2705<DD> 2706--- 2707 2708<DT>Documentation 2709<DD> 2710Included in <CODE>libintl-perl</CODE>, available on CPAN 2711(http://www.cpan.org/). 2712 2713</DL> 2714 2715<P> 2716An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-perl</CODE>. 2717 2718</P> 2719<P> 2720<A NAME="IDX1186"></A> 2721 2722</P> 2723<P> 2724The <CODE>xgettext</CODE> parser backend for Perl differs significantly from 2725the parser backends for other programming languages, just as Perl 2726itself differs significantly from other programming languages. The 2727Perl parser backend offers many more string marking facilities than 2728the other backends but it also has some Perl specific limitations, the 2729worst probably being its imperfectness. 2730 2731</P> 2732 2733 2734 2735<H4><A NAME="SEC280" HREF="gettext_toc.html#TOC280">15.5.18.1 General Problems Parsing Perl Code</A></H4> 2736 2737<P> 2738It is often heard that only Perl can parse Perl. This is not true. 2739Perl cannot be <EM>parsed</EM> at all, it can only be <EM>executed</EM>. 2740Perl has various built-in ambiguities that can only be resolved at runtime. 2741 2742</P> 2743<P> 2744The following example may illustrate one common problem: 2745 2746</P> 2747 2748<PRE> 2749print gettext "Hello World!"; 2750</PRE> 2751 2752<P> 2753Although this example looks like a bullet-proof case of a function 2754invocation, it is not: 2755 2756</P> 2757 2758<PRE> 2759open gettext, ">testfile" or die; 2760print gettext "Hello world!" 2761</PRE> 2762 2763<P> 2764In this context, the string <CODE>gettext</CODE> looks more like a 2765file handle. But not necessarily: 2766 2767</P> 2768 2769<PRE> 2770use Locale::Messages qw (:libintl_h); 2771open gettext ">testfile" or die; 2772print gettext "Hello world!"; 2773</PRE> 2774 2775<P> 2776Now, the file is probably syntactically incorrect, provided that the module 2777<CODE>Locale::Messages</CODE> found first in the Perl include path exports a 2778function <CODE>gettext</CODE>. But what if the module 2779<CODE>Locale::Messages</CODE> really looks like this? 2780 2781</P> 2782 2783<PRE> 2784use vars qw (*gettext); 2785 27861; 2787</PRE> 2788 2789<P> 2790In this case, the string <CODE>gettext</CODE> will be interpreted as a file 2791handle again, and the above example will create a file <TT>‘testfile’</TT> 2792and write the string “Hello world!” into it. Even advanced 2793control flow analysis will not really help: 2794 2795</P> 2796 2797<PRE> 2798if (0.5 < rand) { 2799 eval "use Sane"; 2800} else { 2801 eval "use InSane"; 2802} 2803print gettext "Hello world!"; 2804</PRE> 2805 2806<P> 2807If the module <CODE>Sane</CODE> exports a function <CODE>gettext</CODE> that does 2808what we expect, and the module <CODE>InSane</CODE> opens a file for writing 2809and associates the <EM>handle</EM> <CODE>gettext</CODE> with this output 2810stream, we are clueless again about what will happen at runtime. It is 2811completely unpredictable. The truth is that Perl has so many ways to 2812fill its symbol table at runtime that it is impossible to interpret a 2813particular piece of code without executing it. 2814 2815</P> 2816<P> 2817Of course, <CODE>xgettext</CODE> will not execute your Perl sources while 2818scanning for translatable strings, but rather use heuristics in order 2819to guess what you meant. 2820 2821</P> 2822<P> 2823Another problem is the ambiguity of the slash and the question mark. 2824Their interpretation depends on the context: 2825 2826</P> 2827 2828<PRE> 2829# A pattern match. 2830print "OK\n" if /foobar/; 2831 2832# A division. 2833print 1 / 2; 2834 2835# Another pattern match. 2836print "OK\n" if ?foobar?; 2837 2838# Conditional. 2839print $x ? "foo" : "bar"; 2840</PRE> 2841 2842<P> 2843The slash may either act as the division operator or introduce a 2844pattern match, whereas the question mark may act as the ternary 2845conditional operator or as a pattern match, too. Other programming 2846languages like <CODE>awk</CODE> present similar problems, but the consequences of a 2847misinterpretation are particularly nasty with Perl sources. In <CODE>awk</CODE> 2848for instance, a statement can never exceed one line and the parser 2849can recover from a parsing error at the next newline and interpret 2850the rest of the input stream correctly. Perl is different, as a 2851pattern match is terminated by the next appearance of the delimiter 2852(the slash or the question mark) in the input stream, regardless of 2853the semantic context. If a slash is really a division sign but 2854mis-interpreted as a pattern match, the rest of the input file is most 2855probably parsed incorrectly. 2856 2857</P> 2858<P> 2859If you find that <CODE>xgettext</CODE> fails to extract strings from 2860portions of your sources, you should therefore look out for slashes 2861and/or question marks preceding these sections. You may have come 2862across a bug in <CODE>xgettext</CODE>'s Perl parser (and of course you 2863should report that bug). In the meantime you should consider to 2864reformulate your code in a manner less challenging to <CODE>xgettext</CODE>. 2865 2866</P> 2867 2868 2869<H4><A NAME="SEC281" HREF="gettext_toc.html#TOC281">15.5.18.2 Which keywords will xgettext look for?</A></H4> 2870<P> 2871<A NAME="IDX1187"></A> 2872 2873</P> 2874<P> 2875Unless you instruct <CODE>xgettext</CODE> otherwise by invoking it with one 2876of the options <CODE>--keyword</CODE> or <CODE>-k</CODE>, it will recognize the 2877following keywords in your Perl sources: 2878 2879</P> 2880 2881<UL> 2882 2883<LI><CODE>gettext</CODE> 2884 2885<LI><CODE>dgettext</CODE> 2886 2887<LI><CODE>dcgettext</CODE> 2888 2889<LI><CODE>ngettext:1,2</CODE> 2890 2891The first (singular) and the second (plural) argument will be 2892extracted. 2893 2894<LI><CODE>dngettext:1,2</CODE> 2895 2896The first (singular) and the second (plural) argument will be 2897extracted. 2898 2899<LI><CODE>dcngettext:1,2</CODE> 2900 2901The first (singular) and the second (plural) argument will be 2902extracted. 2903 2904<LI><CODE>gettext_noop</CODE> 2905 2906<LI><CODE>%gettext</CODE> 2907 2908The keys of lookups into the hash <CODE>%gettext</CODE> will be extracted. 2909 2910<LI><CODE>$gettext</CODE> 2911 2912The keys of lookups into the hash reference <CODE>$gettext</CODE> will be extracted. 2913 2914</UL> 2915 2916 2917 2918<H4><A NAME="SEC282" HREF="gettext_toc.html#TOC282">15.5.18.3 How to Extract Hash Keys</A></H4> 2919<P> 2920<A NAME="IDX1188"></A> 2921 2922</P> 2923<P> 2924Translating messages at runtime is normally performed by looking up the 2925original string in the translation database and returning the 2926translated version. The “natural” Perl implementation is a hash 2927lookup, and, of course, <CODE>xgettext</CODE> supports such practice. 2928 2929</P> 2930 2931<PRE> 2932print __"Hello world!"; 2933print $__{"Hello world!"}; 2934print $__->{"Hello world!"}; 2935print $$__{"Hello world!"}; 2936</PRE> 2937 2938<P> 2939The above four lines all do the same thing. The Perl module 2940<CODE>Locale::TextDomain</CODE> exports by default a hash <CODE>%__</CODE> that 2941is tied to the function <CODE>__()</CODE>. It also exports a reference 2942<CODE>$__</CODE> to <CODE>%__</CODE>. 2943 2944</P> 2945<P> 2946If an argument to the <CODE>xgettext</CODE> option <CODE>--keyword</CODE>, 2947resp. <CODE>-k</CODE> starts with a percent sign, the rest of the keyword is 2948interpreted as the name of a hash. If it starts with a dollar 2949sign, the rest of the keyword is interpreted as a reference to a 2950hash. 2951 2952</P> 2953<P> 2954Note that you can omit the quotation marks (single or double) around 2955the hash key (almost) whenever Perl itself allows it: 2956 2957</P> 2958 2959<PRE> 2960print $gettext{Error}; 2961</PRE> 2962 2963<P> 2964The exact rule is: You can omit the surrounding quotes, when the hash 2965key is a valid C (!) identifier, i.e. when it starts with an 2966underscore or an ASCII letter and is followed by an arbitrary number 2967of underscores, ASCII letters or digits. Other Unicode characters 2968are <EM>not</EM> allowed, regardless of the <CODE>use utf8</CODE> pragma. 2969 2970</P> 2971 2972 2973<H4><A NAME="SEC283" HREF="gettext_toc.html#TOC283">15.5.18.4 What are Strings And Quote-like Expressions?</A></H4> 2974<P> 2975<A NAME="IDX1189"></A> 2976 2977</P> 2978<P> 2979Perl offers a plethora of different string constructs. Those that can 2980be used either as arguments to functions or inside braces for hash 2981lookups are generally supported by <CODE>xgettext</CODE>. 2982 2983</P> 2984 2985<UL> 2986<LI><STRONG>double-quoted strings</STRONG> 2987 2988<BR> 2989 2990<PRE> 2991print gettext "Hello World!"; 2992</PRE> 2993 2994<LI><STRONG>single-quoted strings</STRONG> 2995 2996<BR> 2997 2998<PRE> 2999print gettext 'Hello World!'; 3000</PRE> 3001 3002<LI><STRONG>the operator qq</STRONG> 3003 3004<BR> 3005 3006<PRE> 3007print gettext qq |Hello World!|; 3008print gettext qq <E-mail: <guido\@imperia.net>>; 3009</PRE> 3010 3011The operator <CODE>qq</CODE> is fully supported. You can use arbitrary 3012delimiters, including the four bracketing delimiters (round, angle, 3013square, curly) that nest. 3014 3015<LI><STRONG>the operator q</STRONG> 3016 3017<BR> 3018 3019<PRE> 3020print gettext q |Hello World!|; 3021print gettext q <E-mail: <guido@imperia.net>>; 3022</PRE> 3023 3024The operator <CODE>q</CODE> is fully supported. You can use arbitrary 3025delimiters, including the four bracketing delimiters (round, angle, 3026square, curly) that nest. 3027 3028<LI><STRONG>the operator qx</STRONG> 3029 3030<BR> 3031 3032<PRE> 3033print gettext qx ;LANGUAGE=C /bin/date; 3034print gettext qx [/usr/bin/ls | grep '^[A-Z]*']; 3035</PRE> 3036 3037The operator <CODE>qx</CODE> is fully supported. You can use arbitrary 3038delimiters, including the four bracketing delimiters (round, angle, 3039square, curly) that nest. 3040 3041The example is actually a useless use of <CODE>gettext</CODE>. It will 3042invoke the <CODE>gettext</CODE> function on the output of the command 3043specified with the <CODE>qx</CODE> operator. The feature was included 3044in order to make the interface consistent (the parser will extract 3045all strings and quote-like expressions). 3046 3047<LI><STRONG>here documents</STRONG> 3048 3049<BR> 3050 3051<PRE> 3052print gettext <<'EOF'; 3053program not found in $PATH 3054EOF 3055 3056print ngettext <<EOF, <<"EOF"; 3057one file deleted 3058EOF 3059several files deleted 3060EOF 3061</PRE> 3062 3063Here-documents are recognized. If the delimiter is enclosed in single 3064quotes, the string is not interpolated. If it is enclosed in double 3065quotes or has no quotes at all, the string is interpolated. 3066 3067Delimiters that start with a digit are not supported! 3068 3069</UL> 3070 3071 3072 3073<H4><A NAME="SEC284" HREF="gettext_toc.html#TOC284">15.5.18.5 Invalid Uses Of String Interpolation</A></H4> 3074<P> 3075<A NAME="IDX1190"></A> 3076 3077</P> 3078<P> 3079Perl is capable of interpolating variables into strings. This offers 3080some nice features in localized programs but can also lead to 3081problems. 3082 3083</P> 3084<P> 3085A common error is a construct like the following: 3086 3087</P> 3088 3089<PRE> 3090print gettext "This is the program $0!\n"; 3091</PRE> 3092 3093<P> 3094Perl will interpolate at runtime the value of the variable <CODE>$0</CODE> 3095into the argument of the <CODE>gettext()</CODE> function. Hence, this 3096argument is not a string constant but a variable argument (<CODE>$0</CODE> 3097is a global variable that holds the name of the Perl script being 3098executed). The interpolation is performed by Perl before the string 3099argument is passed to <CODE>gettext()</CODE> and will therefore depend on 3100the name of the script which can only be determined at runtime. 3101Consequently, it is almost impossible that a translation can be looked 3102up at runtime (except if, by accident, the interpolated string is found 3103in the message catalog). 3104 3105</P> 3106<P> 3107The <CODE>xgettext</CODE> program will therefore terminate parsing with a fatal 3108error if it encounters a variable inside of an extracted string. In 3109general, this will happen for all kinds of string interpolations that 3110cannot be safely performed at compile time. If you absolutely know 3111what you are doing, you can always circumvent this behavior: 3112 3113</P> 3114 3115<PRE> 3116my $know_what_i_am_doing = "This is program $0!\n"; 3117print gettext $know_what_i_am_doing; 3118</PRE> 3119 3120<P> 3121Since the parser only recognizes strings and quote-like expressions, 3122but not variables or other terms, the above construct will be 3123accepted. You will have to find another way, however, to let your 3124original string make it into your message catalog. 3125 3126</P> 3127<P> 3128If invoked with the option <CODE>--extract-all</CODE>, resp. <CODE>-a</CODE>, 3129variable interpolation will be accepted. Rationale: You will 3130generally use this option in order to prepare your sources for 3131internationalization. 3132 3133</P> 3134<P> 3135Please see the manual page <SAMP>‘man perlop’</SAMP> for details of strings and 3136quote-like expressions that are subject to interpolation and those 3137that are not. Safe interpolations (that will not lead to a fatal 3138error) are: 3139 3140</P> 3141 3142<UL> 3143 3144<LI>the escape sequences <CODE>\t</CODE> (tab, HT, TAB), <CODE>\n</CODE> 3145 3146(newline, NL), <CODE>\r</CODE> (return, CR), <CODE>\f</CODE> (form feed, FF), 3147<CODE>\b</CODE> (backspace, BS), <CODE>\a</CODE> (alarm, bell, BEL), and <CODE>\e</CODE> 3148(escape, ESC). 3149 3150<LI>octal chars, like <CODE>\033</CODE> 3151 3152<BR> 3153Note that octal escapes in the range of 400-777 are translated into a 3154UTF-8 representation, regardless of the presence of the <CODE>use utf8</CODE> pragma. 3155 3156<LI>hex chars, like <CODE>\x1b</CODE> 3157 3158<LI>wide hex chars, like <CODE>\x{263a}</CODE> 3159 3160<BR> 3161Note that this escape is translated into a UTF-8 representation, 3162regardless of the presence of the <CODE>use utf8</CODE> pragma. 3163 3164<LI>control chars, like <CODE>\c[</CODE> (CTRL-[) 3165 3166<LI>named Unicode chars, like <CODE>\N{LATIN CAPITAL LETTER C WITH CEDILLA}</CODE> 3167 3168<BR> 3169Note that this escape is translated into a UTF-8 representation, 3170regardless of the presence of the <CODE>use utf8</CODE> pragma. 3171</UL> 3172 3173<P> 3174The following escapes are considered partially safe: 3175 3176</P> 3177 3178<UL> 3179 3180<LI><CODE>\l</CODE> lowercase next char 3181 3182<LI><CODE>\u</CODE> uppercase next char 3183 3184<LI><CODE>\L</CODE> lowercase till \E 3185 3186<LI><CODE>\U</CODE> uppercase till \E 3187 3188<LI><CODE>\E</CODE> end case modification 3189 3190<LI><CODE>\Q</CODE> quote non-word characters till \E 3191 3192</UL> 3193 3194<P> 3195These escapes are only considered safe if the string consists of 3196ASCII characters only. Translation of characters outside the range 3197defined by ASCII is locale-dependent and can actually only be performed 3198at runtime; <CODE>xgettext</CODE> doesn't do these locale-dependent translations 3199at extraction time. 3200 3201</P> 3202<P> 3203Except for the modifier <CODE>\Q</CODE>, these translations, albeit valid, 3204are generally useless and only obfuscate your sources. If a 3205translation can be safely performed at compile time you can just as 3206well write what you mean. 3207 3208</P> 3209 3210 3211<H4><A NAME="SEC285" HREF="gettext_toc.html#TOC285">15.5.18.6 Valid Uses Of String Interpolation</A></H4> 3212<P> 3213<A NAME="IDX1191"></A> 3214 3215</P> 3216<P> 3217Perl is often used to generate sources for other programming languages 3218or arbitrary file formats. Web applications that output HTML code 3219make a prominent example for such usage. 3220 3221</P> 3222<P> 3223You will often come across situations where you want to intersperse 3224code written in the target (programming) language with translatable 3225messages, like in the following HTML example: 3226 3227</P> 3228 3229<PRE> 3230print gettext <<EOF; 3231<h1>My Homepage</h1> 3232<script language="JavaScript"><!-- 3233for (i = 0; i < 100; ++i) { 3234 alert ("Thank you so much for visiting my homepage!"); 3235} 3236//--></script> 3237EOF 3238</PRE> 3239 3240<P> 3241The parser will extract the entire here document, and it will appear 3242entirely in the resulting PO file, including the JavaScript snippet 3243embedded in the HTML code. If you exaggerate with constructs like 3244the above, you will run the risk that the translators of your package 3245will look out for a less challenging project. You should consider an 3246alternative expression here: 3247 3248</P> 3249 3250<PRE> 3251print <<EOF; 3252<h1>$gettext{"My Homepage"}</h1> 3253<script language="JavaScript"><!-- 3254for (i = 0; i < 100; ++i) { 3255 alert ("$gettext{'Thank you so much for visiting my homepage!'}"); 3256} 3257//--></script> 3258EOF 3259</PRE> 3260 3261<P> 3262Only the translatable portions of the code will be extracted here, and 3263the resulting PO file will begrudgingly improve in terms of readability. 3264 3265</P> 3266<P> 3267You can interpolate hash lookups in all strings or quote-like 3268expressions that are subject to interpolation (see the manual page 3269<SAMP>‘man perlop’</SAMP> for details). Double interpolation is invalid, however: 3270 3271</P> 3272 3273<PRE> 3274# TRANSLATORS: Replace "the earth" with the name of your planet. 3275print gettext qq{Welcome to $gettext->{"the earth"}}; 3276</PRE> 3277 3278<P> 3279The <CODE>qq</CODE>-quoted string is recognized as an argument to <CODE>xgettext</CODE> in 3280the first place, and checked for invalid variable interpolation. The 3281dollar sign of hash-dereferencing will therefore terminate the parser 3282with an “invalid interpolation” error. 3283 3284</P> 3285<P> 3286It is valid to interpolate hash lookups in regular expressions: 3287 3288</P> 3289 3290<PRE> 3291if ($var =~ /$gettext{"the earth"}/) { 3292 print gettext "Match!\n"; 3293} 3294s/$gettext{"U. S. A."}/$gettext{"U. S. A."} $gettext{"(dial +0)"}/g; 3295</PRE> 3296 3297 3298 3299<H4><A NAME="SEC286" HREF="gettext_toc.html#TOC286">15.5.18.7 When To Use Parentheses</A></H4> 3300<P> 3301<A NAME="IDX1192"></A> 3302 3303</P> 3304<P> 3305In Perl, parentheses around function arguments are mostly optional. 3306<CODE>xgettext</CODE> will always assume that all 3307recognized keywords (except for hashes and hash references) are names 3308of properly prototyped functions, and will (hopefully) only require 3309parentheses where Perl itself requires them. All constructs in the 3310following example are therefore ok to use: 3311 3312</P> 3313 3314<PRE> 3315print gettext ("Hello World!\n"); 3316print gettext "Hello World!\n"; 3317print dgettext ($package => "Hello World!\n"); 3318print dgettext $package, "Hello World!\n"; 3319 3320# The "fat comma" => turns the left-hand side argument into a 3321# single-quoted string! 3322print dgettext smellovision => "Hello World!\n"; 3323 3324# The following assignment only works with prototyped functions. 3325# Otherwise, the functions will act as "greedy" list operators and 3326# eat up all following arguments. 3327my $anonymous_hash = { 3328 planet => gettext "earth", 3329 cakes => ngettext "one cake", "several cakes", $n, 3330 still => $works, 3331}; 3332# The same without fat comma: 3333my $other_hash = { 3334 'planet', gettext "earth", 3335 'cakes', ngettext "one cake", "several cakes", $n, 3336 'still', $works, 3337}; 3338 3339# Parentheses are only significant for the first argument. 3340print dngettext 'package', ("one cake", "several cakes", $n), $discarded; 3341</PRE> 3342 3343 3344 3345<H4><A NAME="SEC287" HREF="gettext_toc.html#TOC287">15.5.18.8 How To Grok with Long Lines</A></H4> 3346<P> 3347<A NAME="IDX1193"></A> 3348 3349</P> 3350<P> 3351The necessity of long messages can often lead to a cumbersome or 3352unreadable coding style. Perl has several options that may prevent 3353you from writing unreadable code, and 3354<CODE>xgettext</CODE> does its best to do likewise. This is where the dot 3355operator (the string concatenation operator) may come in handy: 3356 3357</P> 3358 3359<PRE> 3360print gettext ("This is a very long" 3361 . " message that is still" 3362 . " readable, because" 3363 . " it is split into" 3364 . " multiple lines.\n"); 3365</PRE> 3366 3367<P> 3368Perl is smart enough to concatenate these constant string fragments 3369into one long string at compile time, and so is 3370<CODE>xgettext</CODE>. You will only find one long message in the resulting 3371POT file. 3372 3373</P> 3374<P> 3375Note that the future Perl 6 will probably use the underscore 3376(<SAMP>‘_’</SAMP>) as the string concatenation operator, and the dot 3377(<SAMP>‘.’</SAMP>) for dereferencing. This new syntax is not yet supported by 3378<CODE>xgettext</CODE>. 3379 3380</P> 3381<P> 3382If embedded newline characters are not an issue, or even desired, you 3383may also insert newline characters inside quoted strings wherever you 3384feel like it: 3385 3386</P> 3387 3388<PRE> 3389print gettext ("<em>In HTML output 3390embedded newlines are generally no 3391problem, since adjacent whitespace 3392is always rendered into a single 3393space character.</em>"); 3394</PRE> 3395 3396<P> 3397You may also consider to use here documents: 3398 3399</P> 3400 3401<PRE> 3402print gettext <<EOF; 3403<em>In HTML output 3404embedded newlines are generally no 3405problem, since adjacent whitespace 3406is always rendered into a single 3407space character.</em> 3408EOF 3409</PRE> 3410 3411<P> 3412Please do not forget that the line breaks are real, i.e. they 3413translate into newline characters that will consequently show up in 3414the resulting POT file. 3415 3416</P> 3417 3418 3419<H4><A NAME="SEC288" HREF="gettext_toc.html#TOC288">15.5.18.9 Bugs, Pitfalls, And Things That Do Not Work</A></H4> 3420<P> 3421<A NAME="IDX1194"></A> 3422 3423</P> 3424<P> 3425The foregoing sections should have proven that 3426<CODE>xgettext</CODE> is quite smart in extracting translatable strings from 3427Perl sources. Yet, some more or less exotic constructs that could be 3428expected to work, actually do not work. 3429 3430</P> 3431<P> 3432One of the more relevant limitations can be found in the 3433implementation of variable interpolation inside quoted strings. Only 3434simple hash lookups can be used there: 3435 3436</P> 3437 3438<PRE> 3439print <<EOF; 3440$gettext{"The dot operator" 3441 . " does not work" 3442 . "here!"} 3443Likewise, you cannot @{[ gettext ("interpolate function calls") ]} 3444inside quoted strings or quote-like expressions. 3445EOF 3446</PRE> 3447 3448<P> 3449This is valid Perl code and will actually trigger invocations of the 3450<CODE>gettext</CODE> function at runtime. Yet, the Perl parser in 3451<CODE>xgettext</CODE> will fail to recognize the strings. A less obvious 3452example can be found in the interpolation of regular expressions: 3453 3454</P> 3455 3456<PRE> 3457s/<!--START_OF_WEEK-->/gettext ("Sunday")/e; 3458</PRE> 3459 3460<P> 3461The modifier <CODE>e</CODE> will cause the substitution to be interpreted as 3462an evaluable statement. Consequently, at runtime the function 3463<CODE>gettext()</CODE> is called, but again, the parser fails to extract the 3464string “Sunday”. Use a temporary variable as a simple workaround if 3465you really happen to need this feature: 3466 3467</P> 3468 3469<PRE> 3470my $sunday = gettext "Sunday"; 3471s/<!--START_OF_WEEK-->/$sunday/; 3472</PRE> 3473 3474<P> 3475Hash slices would also be handy but are not recognized: 3476 3477</P> 3478 3479<PRE> 3480my @weekdays = @gettext{'Sunday', 'Monday', 'Tuesday', 'Wednesday', 3481 'Thursday', 'Friday', 'Saturday'}; 3482# Or even: 3483@weekdays = @gettext{qw (Sunday Monday Tuesday Wednesday Thursday 3484 Friday Saturday) }; 3485</PRE> 3486 3487<P> 3488This is perfectly valid usage of the tied hash <CODE>%gettext</CODE> but the 3489strings are not recognized and therefore will not be extracted. 3490 3491</P> 3492<P> 3493Another caveat of the current version is its rudimentary support for 3494non-ASCII characters in identifiers. You may encounter serious 3495problems if you use identifiers with characters outside the range of 3496'A'-'Z', 'a'-'z', '0'-'9' and the underscore '_'. 3497 3498</P> 3499<P> 3500Maybe some of these missing features will be implemented in future 3501versions, but since you can always make do without them at minimal effort, 3502these todos have very low priority. 3503 3504</P> 3505<P> 3506A nasty problem are brace format strings that already contain braces 3507as part of the normal text, for example the usage strings typically 3508encountered in programs: 3509 3510</P> 3511 3512<PRE> 3513die "usage: $0 {OPTIONS} FILENAME...\n"; 3514</PRE> 3515 3516<P> 3517If you want to internationalize this code with Perl brace format strings, 3518you will run into a problem: 3519 3520</P> 3521 3522<PRE> 3523die __x ("usage: {program} {OPTIONS} FILENAME...\n", program => $0); 3524</PRE> 3525 3526<P> 3527Whereas <SAMP>‘{program}’</SAMP> is a placeholder, <SAMP>‘{OPTIONS}’</SAMP> 3528is not and should probably be translated. Yet, there is no way to teach 3529the Perl parser in <CODE>xgettext</CODE> to recognize the first one, and leave 3530the other one alone. 3531 3532</P> 3533<P> 3534There are two possible work-arounds for this problem. If you are 3535sure that your program will run under Perl 5.8.0 or newer (these 3536Perl versions handle positional parameters in <CODE>printf()</CODE>) or 3537if you are sure that the translator will not have to reorder the arguments 3538in her translation -- for example if you have only one brace placeholder 3539in your string, or if it describes a syntax, like in this one --, you can 3540mark the string as <CODE>no-perl-brace-format</CODE> and use <CODE>printf()</CODE>: 3541 3542</P> 3543 3544<PRE> 3545# xgettext: no-perl-brace-format 3546die sprintf ("usage: %s {OPTIONS} FILENAME...\n", $0); 3547</PRE> 3548 3549<P> 3550If you want to use the more portable Perl brace format, you will have to do 3551put placeholders in place of the literal braces: 3552 3553</P> 3554 3555<PRE> 3556die __x ("usage: {program} {[}OPTIONS{]} FILENAME...\n", 3557 program => $0, '[' => '{', ']' => '}'); 3558</PRE> 3559 3560<P> 3561Perl brace format strings know no escaping mechanism. No matter how this 3562escaping mechanism looked like, it would either give the programmer a 3563hard time, make translating Perl brace format strings heavy-going, or 3564result in a performance penalty at runtime, when the format directives 3565get executed. Most of the time you will happily get along with 3566<CODE>printf()</CODE> for this special case. 3567 3568</P> 3569 3570 3571<H3><A NAME="SEC289" HREF="gettext_toc.html#TOC289">15.5.19 PHP Hypertext Preprocessor</A></H3> 3572<P> 3573<A NAME="IDX1195"></A> 3574 3575</P> 3576<DL COMPACT> 3577 3578<DT>RPMs 3579<DD> 3580mod_php4, mod_php4-core, phpdoc 3581 3582<DT>File extension 3583<DD> 3584<CODE>php</CODE>, <CODE>php3</CODE>, <CODE>php4</CODE> 3585 3586<DT>String syntax 3587<DD> 3588<CODE>"abc"</CODE>, <CODE>'abc'</CODE> 3589 3590<DT>gettext shorthand 3591<DD> 3592<CODE>_("abc")</CODE> 3593 3594<DT>gettext/ngettext functions 3595<DD> 3596<CODE>gettext</CODE>, <CODE>dgettext</CODE>, <CODE>dcgettext</CODE>; starting with PHP 4.2.0 3597also <CODE>ngettext</CODE>, <CODE>dngettext</CODE>, <CODE>dcngettext</CODE> 3598 3599<DT>textdomain 3600<DD> 3601<CODE>textdomain</CODE> function 3602 3603<DT>bindtextdomain 3604<DD> 3605<CODE>bindtextdomain</CODE> function 3606 3607<DT>setlocale 3608<DD> 3609Programmer must call <CODE>setlocale (LC_ALL, "")</CODE> 3610 3611<DT>Prerequisite 3612<DD> 3613--- 3614 3615<DT>Use or emulate GNU gettext 3616<DD> 3617use 3618 3619<DT>Extractor 3620<DD> 3621<CODE>xgettext</CODE> 3622 3623<DT>Formatting with positions 3624<DD> 3625<CODE>printf "%2\$d %1\$d"</CODE> 3626 3627<DT>Portability 3628<DD> 3629On platforms without gettext, the functions are not available. 3630 3631<DT>po-mode marking 3632<DD> 3633--- 3634</DL> 3635 3636<P> 3637An example is available in the <TT>‘examples’</TT> directory: <CODE>hello-php</CODE>. 3638 3639</P> 3640 3641 3642<H3><A NAME="SEC290" HREF="gettext_toc.html#TOC290">15.5.20 Pike</A></H3> 3643<P> 3644<A NAME="IDX1196"></A> 3645 3646</P> 3647<DL COMPACT> 3648 3649<DT>RPMs 3650<DD> 3651roxen 3652 3653<DT>File extension 3654<DD> 3655<CODE>pike</CODE> 3656 3657<DT>String syntax 3658<DD> 3659<CODE>"abc"</CODE> 3660 3661<DT>gettext shorthand 3662<DD> 3663--- 3664 3665<DT>gettext/ngettext functions 3666<DD> 3667<CODE>gettext</CODE>, <CODE>dgettext</CODE>, <CODE>dcgettext</CODE> 3668 3669<DT>textdomain 3670<DD> 3671<CODE>textdomain</CODE> function 3672 3673<DT>bindtextdomain 3674<DD> 3675<CODE>bindtextdomain</CODE> function 3676 3677<DT>setlocale 3678<DD> 3679<CODE>setlocale</CODE> function 3680 3681<DT>Prerequisite 3682<DD> 3683<CODE>import Locale.Gettext;</CODE> 3684 3685<DT>Use or emulate GNU gettext 3686<DD> 3687use 3688 3689<DT>Extractor 3690<DD> 3691--- 3692 3693<DT>Formatting with positions 3694<DD> 3695--- 3696 3697<DT>Portability 3698<DD> 3699On platforms without gettext, the functions are not available. 3700 3701<DT>po-mode marking 3702<DD> 3703--- 3704</DL> 3705 3706 3707 3708<H3><A NAME="SEC291" HREF="gettext_toc.html#TOC291">15.5.21 GNU Compiler Collection sources</A></H3> 3709<P> 3710<A NAME="IDX1197"></A> 3711 3712</P> 3713<DL COMPACT> 3714 3715<DT>RPMs 3716<DD> 3717gcc 3718 3719<DT>File extension 3720<DD> 3721<CODE>c</CODE>, <CODE>h</CODE>. 3722 3723<DT>String syntax 3724<DD> 3725<CODE>"abc"</CODE> 3726 3727<DT>gettext shorthand 3728<DD> 3729<CODE>_("abc")</CODE> 3730 3731<DT>gettext/ngettext functions 3732<DD> 3733<CODE>gettext</CODE>, <CODE>dgettext</CODE>, <CODE>dcgettext</CODE>, <CODE>ngettext</CODE>, 3734<CODE>dngettext</CODE>, <CODE>dcngettext</CODE> 3735 3736<DT>textdomain 3737<DD> 3738<CODE>textdomain</CODE> function 3739 3740<DT>bindtextdomain 3741<DD> 3742<CODE>bindtextdomain</CODE> function 3743 3744<DT>setlocale 3745<DD> 3746Programmer must call <CODE>setlocale (LC_ALL, "")</CODE> 3747 3748<DT>Prerequisite 3749<DD> 3750<CODE>#include "intl.h"</CODE> 3751 3752<DT>Use or emulate GNU gettext 3753<DD> 3754Use 3755 3756<DT>Extractor 3757<DD> 3758<CODE>xgettext -k_</CODE> 3759 3760<DT>Formatting with positions 3761<DD> 3762--- 3763 3764<DT>Portability 3765<DD> 3766Uses autoconf macros 3767 3768<DT>po-mode marking 3769<DD> 3770yes 3771</DL> 3772 3773 3774 3775<H2><A NAME="SEC292" HREF="gettext_toc.html#TOC292">15.6 Internationalizable Data</A></H2> 3776 3777<P> 3778Here is a list of other data formats which can be internationalized 3779using GNU gettext. 3780 3781</P> 3782 3783 3784 3785<H3><A NAME="SEC293" HREF="gettext_toc.html#TOC293">15.6.1 POT - Portable Object Template</A></H3> 3786 3787<DL COMPACT> 3788 3789<DT>RPMs 3790<DD> 3791gettext 3792 3793<DT>File extension 3794<DD> 3795<CODE>pot</CODE>, <CODE>po</CODE> 3796 3797<DT>Extractor 3798<DD> 3799<CODE>xgettext</CODE> 3800</DL> 3801 3802 3803 3804<H3><A NAME="SEC294" HREF="gettext_toc.html#TOC294">15.6.2 Resource String Table</A></H3> 3805<P> 3806<A NAME="IDX1198"></A> 3807 3808</P> 3809<DL COMPACT> 3810 3811<DT>RPMs 3812<DD> 3813fpk 3814 3815<DT>File extension 3816<DD> 3817<CODE>rst</CODE> 3818 3819<DT>Extractor 3820<DD> 3821<CODE>xgettext</CODE>, <CODE>rstconv</CODE> 3822</DL> 3823 3824 3825 3826<H3><A NAME="SEC295" HREF="gettext_toc.html#TOC295">15.6.3 Glade - GNOME user interface description</A></H3> 3827 3828<DL COMPACT> 3829 3830<DT>RPMs 3831<DD> 3832glade, libglade, glade2, libglade2, intltool 3833 3834<DT>File extension 3835<DD> 3836<CODE>glade</CODE>, <CODE>glade2</CODE> 3837 3838<DT>Extractor 3839<DD> 3840<CODE>xgettext</CODE>, <CODE>libglade-xgettext</CODE>, <CODE>xml-i18n-extract</CODE>, <CODE>intltool-extract</CODE> 3841</DL> 3842 3843<P><HR><P> 3844Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_14.html">previous</A>, <A HREF="gettext_16.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. 3845</BODY> 3846</HTML> 3847