gettext-tools/doc/gettext_15.html

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