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

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.52a
   4      from gettext.texi on 23 May 2005 -->
   5
   6 <TITLE>GNU gettext utilities - 7  Manipulating PO Files</TITLE>
   7 </HEAD>
   8 <BODY>
   9 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_6.html">previous</A>, <A HREF="gettext_8.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
  10 <P><HR><P>
  11
  12
  13 <H1><A NAME="SEC66" HREF="gettext_toc.html#TOC66">7  Manipulating PO Files</A></H1>
  14 <P>
  15 <A NAME="IDX484"></A>
  16
  17 </P>
  18 <P>
  19 Sometimes it is necessary to manipulate PO files in a way that is better
  20 performed automatically than by hand.  GNU <CODE>gettext</CODE> includes a
  21 complete set of tools for this purpose.
  22
  23 </P>
  24 <P>
  25 <A NAME="IDX485"></A>
  26 When merging two packages into a single package, the resulting POT file
  27 will be the concatenation of the two packages' POT files.  Thus the
  28 maintainer must concatenate the two existing package translations into
  29 a single translation catalog, for each language.  This is best performed
  30 using <SAMP>`msgcat&acute;</SAMP>.  It is then the translators' duty to deal with any
  31 possible conflicts that arose during the merge.
  32
  33 </P>
  34 <P>
  35 <A NAME="IDX486"></A>
  36 When a translator takes over the translation job from another translator,
  37 but she uses a different character encoding in her locale, she will
  38 convert the catalog to her character encoding.  This is best done through
  39 the <SAMP>`msgconv&acute;</SAMP> program.
  40
  41 </P>
  42 <P>
  43 When a maintainer takes a source file with tagged messages from another
  44 package, he should also take the existing translations for this source
  45 file (and not let the translators do the same job twice).  One way to do
  46 this is through <SAMP>`msggrep&acute;</SAMP>, another is to create a POT file for
  47 that source file and use <SAMP>`msgmerge&acute;</SAMP>.
  48
  49 </P>
  50 <P>
  51 <A NAME="IDX487"></A>
  52 <A NAME="IDX488"></A>
  53 When a translator wants to adjust some translation catalog for a special
  54 dialect or orthography -- for example, German as written in Switzerland
  55 versus German as written in Germany -- she needs to apply some text
  56 processing to every message in the catalog.  The tool for doing this is
  57 <SAMP>`msgfilter&acute;</SAMP>.
  58
  59 </P>
  60 <P>
  61 Another use of <CODE>msgfilter</CODE> is to produce approximately the POT file for
  62 which a given PO file was made.  This can be done through a filter command
  63 like <SAMP>`msgfilter sed -e d | sed -e '/^# /d'&acute;</SAMP>.  Note that the original
  64 POT file may have had different comments and different plural message counts,
  65 that's why it's better to use the original POT file if available.
  66
  67 </P>
  68 <P>
  69 <A NAME="IDX489"></A>
  70 When a translator wants to check her translations, for example according
  71 to orthography rules or using a non-interactive spell checker, she can do
  72 so using the <SAMP>`msgexec&acute;</SAMP> program.
  73
  74 </P>
  75 <P>
  76 <A NAME="IDX490"></A>
  77 When third party tools create PO or POT files, sometimes duplicates cannot
  78 be avoided.  But the GNU <CODE>gettext</CODE> tools give an error when they
  79 encounter duplicate msgids in the same file and in the same domain.
  80 To merge duplicates, the <SAMP>`msguniq&acute;</SAMP> program can be used.
  81
  82 </P>
  83 <P>
  84 <SAMP>`msgcomm&acute;</SAMP> is a more general tool for keeping or throwing away
  85 duplicates, occurring in different files.
  86
  87 </P>
  88 <P>
  89 <SAMP>`msgcmp&acute;</SAMP> can be used to check whether a translation catalog is
  90 completely translated.
  91
  92 </P>
  93 <P>
  94 <A NAME="IDX491"></A>
  95 <SAMP>`msgattrib&acute;</SAMP> can be used to select and extract only the fuzzy
  96 or untranslated messages of a translation catalog.
  97
  98 </P>
  99 <P>
 100 <SAMP>`msgen&acute;</SAMP> is useful as a first step for preparing English translation
 101 catalogs.  It copies each message's msgid to its msgstr.
 102
 103 </P>
 104 <P>
 105 Finally, for those applications where all these various programs are not
 106 sufficient, a library <SAMP>`libgettextpo&acute;</SAMP> is provided that can be used to
 107 write other specialized programs that process PO files.
 108
 109 </P>
 110
 111
 112
 113 <H2><A NAME="SEC67" HREF="gettext_toc.html#TOC67">7.1  Invoking the <CODE>msgcat</CODE> Program</A></H2>
 114
 115 <P>
 116 <A NAME="IDX492"></A>
 117 <A NAME="IDX493"></A>
 118
 119 <PRE>
 120 msgcat [<VAR>option</VAR>] [<VAR>inputfile</VAR>]...
 121 </PRE>
 122
 123 <P>
 124 <A NAME="IDX494"></A>
 125 <A NAME="IDX495"></A>
 126 The <CODE>msgcat</CODE> program concatenates and merges the specified PO files.
 127 It finds messages which are common to two or more of the specified PO files.
 128 By using the <CODE>--more-than</CODE> option, greater commonality may be requested
 129 before messages are printed.  Conversely, the <CODE>--less-than</CODE> option may be
 130 used to specify less commonality before messages are printed (i.e.
 131 <SAMP>`--less-than=2&acute;</SAMP> will only print the unique messages).  Translations,
 132 comments and extract comments will be cumulated, except that if
 133 <CODE>--use-first</CODE> is specified, they will be taken from the first PO file
 134 to define them.  File positions from all PO files will be cumulated.
 135
 136 </P>
 137
 138
 139 <H3><A NAME="SEC68" HREF="gettext_toc.html#TOC68">7.1.1  Input file location</A></H3>
 140
 141 <DL COMPACT>
 142
 143 <DT><SAMP>`<VAR>inputfile</VAR> ...&acute;</SAMP>
 144 <DD>
 145 Input files.
 146
 147 <DT><SAMP>`-f <VAR>file</VAR>&acute;</SAMP>
 148 <DD>
 149 <DT><SAMP>`--files-from=<VAR>file</VAR>&acute;</SAMP>
 150 <DD>
 151 <A NAME="IDX496"></A>
 152 <A NAME="IDX497"></A>
 153 Read the names of the input files from <VAR>file</VAR> instead of getting
 154 them from the command line.
 155
 156 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
 157 <DD>
 158 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
 159 <DD>
 160 <A NAME="IDX498"></A>
 161 <A NAME="IDX499"></A>
 162 Add <VAR>directory</VAR> to the list of directories.  Source files are
 163 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
 164 file will be written relative to the current directory, though.
 165
 166 </DL>
 167
 168 <P>
 169 If <VAR>inputfile</VAR> is <SAMP>`-&acute;</SAMP>, standard input is read.
 170
 171 </P>
 172
 173
 174 <H3><A NAME="SEC69" HREF="gettext_toc.html#TOC69">7.1.2  Output file location</A></H3>
 175
 176 <DL COMPACT>
 177
 178 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
 179 <DD>
 180 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
 181 <DD>
 182 <A NAME="IDX500"></A>
 183 <A NAME="IDX501"></A>
 184 Write output to specified file.
 185
 186 </DL>
 187
 188 <P>
 189 <A NAME="IDX502"></A>
 190 The results are written to standard output if no output file is specified
 191 or if it is <SAMP>`-&acute;</SAMP>.
 192
 193 </P>
 194
 195
 196 <H3><A NAME="SEC70" HREF="gettext_toc.html#TOC70">7.1.3  Message selection</A></H3>
 197
 198 <DL COMPACT>
 199
 200 <DT><SAMP>`-&#60; <VAR>number</VAR>&acute;</SAMP>
 201 <DD>
 202 <DT><SAMP>`--less-than=<VAR>number</VAR>&acute;</SAMP>
 203 <DD>
 204 <A NAME="IDX503"></A>
 205 <A NAME="IDX504"></A>
 206 Print messages with less than <VAR>number</VAR> definitions, defaults to infinite
 207 if not set.
 208
 209 <DT><SAMP>`-&#62; <VAR>number</VAR>&acute;</SAMP>
 210 <DD>
 211 <DT><SAMP>`--more-than=<VAR>number</VAR>&acute;</SAMP>
 212 <DD>
 213 <A NAME="IDX505"></A>
 214 <A NAME="IDX506"></A>
 215 Print messages with more than <VAR>number</VAR> definitions, defaults to 0 if not
 216 set.
 217
 218 <DT><SAMP>`-u&acute;</SAMP>
 219 <DD>
 220 <DT><SAMP>`--unique&acute;</SAMP>
 221 <DD>
 222 <A NAME="IDX507"></A>
 223 <A NAME="IDX508"></A>
 224 Shorthand for <SAMP>`--less-than=2&acute;</SAMP>.  Requests that only unique messages be
 225 printed.
 226
 227 </DL>
 228
 229
 230
 231 <H3><A NAME="SEC71" HREF="gettext_toc.html#TOC71">7.1.4  Input file syntax</A></H3>
 232
 233 <DL COMPACT>
 234
 235 <DT><SAMP>`-P&acute;</SAMP>
 236 <DD>
 237 <DT><SAMP>`--properties-input&acute;</SAMP>
 238 <DD>
 239 <A NAME="IDX509"></A>
 240 <A NAME="IDX510"></A>
 241 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
 242 syntax, not in PO file syntax.
 243
 244 <DT><SAMP>`--stringtable-input&acute;</SAMP>
 245 <DD>
 246 <A NAME="IDX511"></A>
 247 Assume the input files are NeXTstep/GNUstep localized resource files in
 248 <CODE>.strings</CODE> syntax, not in PO file syntax.
 249
 250 </DL>
 251
 252
 253
 254 <H3><A NAME="SEC72" HREF="gettext_toc.html#TOC72">7.1.5  Output details</A></H3>
 255
 256 <DL COMPACT>
 257
 258 <DT><SAMP>`-t&acute;</SAMP>
 259 <DD>
 260 <DT><SAMP>`--to-code=<VAR>name</VAR>&acute;</SAMP>
 261 <DD>
 262 <A NAME="IDX512"></A>
 263 <A NAME="IDX513"></A>
 264 Specify encoding for output.
 265
 266 <DT><SAMP>`--use-first&acute;</SAMP>
 267 <DD>
 268 <A NAME="IDX514"></A>
 269 Use first available translation for each message.  Don't merge several
 270 translations into one.
 271
 272 <DT><SAMP>`--force-po&acute;</SAMP>
 273 <DD>
 274 <A NAME="IDX515"></A>
 275 Always write an output file even if it contains no message.
 276
 277 <DT><SAMP>`-i&acute;</SAMP>
 278 <DD>
 279 <DT><SAMP>`--indent&acute;</SAMP>
 280 <DD>
 281 <A NAME="IDX516"></A>
 282 <A NAME="IDX517"></A>
 283 Write the .po file using indented style.
 284
 285 <DT><SAMP>`--no-location&acute;</SAMP>
 286 <DD>
 287 <A NAME="IDX518"></A>
 288 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
 289
 290 <DT><SAMP>`-n&acute;</SAMP>
 291 <DD>
 292 <DT><SAMP>`--add-location&acute;</SAMP>
 293 <DD>
 294 <A NAME="IDX519"></A>
 295 <A NAME="IDX520"></A>
 296 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
 297
 298 <DT><SAMP>`--strict&acute;</SAMP>
 299 <DD>
 300 <A NAME="IDX521"></A>
 301 Write out a strict Uniforum conforming PO file.  Note that this
 302 Uniforum format should be avoided because it doesn't support the
 303 GNU extensions.
 304
 305 <DT><SAMP>`-p&acute;</SAMP>
 306 <DD>
 307 <DT><SAMP>`--properties-output&acute;</SAMP>
 308 <DD>
 309 <A NAME="IDX522"></A>
 310 <A NAME="IDX523"></A>
 311 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
 312 that this file format doesn't support plural forms and silently drops
 313 obsolete messages.
 314
 315 <DT><SAMP>`--stringtable-output&acute;</SAMP>
 316 <DD>
 317 <A NAME="IDX524"></A>
 318 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
 319 Note that this file format doesn't support plural forms.
 320
 321 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
 322 <DD>
 323 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
 324 <DD>
 325 <A NAME="IDX525"></A>
 326 <A NAME="IDX526"></A>
 327 Set the output page width.  Long strings in the output files will be
 328 split across multiple lines in order to ensure that each line's width
 329 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
 330
 331 <DT><SAMP>`--no-wrap&acute;</SAMP>
 332 <DD>
 333 <A NAME="IDX527"></A>
 334 Do not break long message lines.  Message lines whose width exceeds the
 335 output page width will not be split into several lines.  Only file reference
 336 lines which are wider than the output page width will be split.
 337
 338 <DT><SAMP>`-s&acute;</SAMP>
 339 <DD>
 340 <DT><SAMP>`--sort-output&acute;</SAMP>
 341 <DD>
 342 <A NAME="IDX528"></A>
 343 <A NAME="IDX529"></A>
 344 <A NAME="IDX530"></A>
 345 Generate sorted output.  Note that using this option makes it much harder
 346 for the translator to understand each message's context.
 347
 348 <DT><SAMP>`-F&acute;</SAMP>
 349 <DD>
 350 <DT><SAMP>`--sort-by-file&acute;</SAMP>
 351 <DD>
 352 <A NAME="IDX531"></A>
 353 <A NAME="IDX532"></A>
 354 Sort output by file location.
 355
 356 </DL>
 357
 358
 359
 360 <H3><A NAME="SEC73" HREF="gettext_toc.html#TOC73">7.1.6  Informative output</A></H3>
 361
 362 <DL COMPACT>
 363
 364 <DT><SAMP>`-h&acute;</SAMP>
 365 <DD>
 366 <DT><SAMP>`--help&acute;</SAMP>
 367 <DD>
 368 <A NAME="IDX533"></A>
 369 <A NAME="IDX534"></A>
 370 Display this help and exit.
 371
 372 <DT><SAMP>`-V&acute;</SAMP>
 373 <DD>
 374 <DT><SAMP>`--version&acute;</SAMP>
 375 <DD>
 376 <A NAME="IDX535"></A>
 377 <A NAME="IDX536"></A>
 378 Output version information and exit.
 379
 380 </DL>
 381
 382
 383
 384 <H2><A NAME="SEC74" HREF="gettext_toc.html#TOC74">7.2  Invoking the <CODE>msgconv</CODE> Program</A></H2>
 385
 386 <P>
 387 <A NAME="IDX537"></A>
 388 <A NAME="IDX538"></A>
 389
 390 <PRE>
 391 msgconv [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
 392 </PRE>
 393
 394 <P>
 395 <A NAME="IDX539"></A>
 396 The <CODE>msgconv</CODE> program converts a translation catalog to a different
 397 character encoding.
 398
 399 </P>
 400
 401
 402 <H3><A NAME="SEC75" HREF="gettext_toc.html#TOC75">7.2.1  Input file location</A></H3>
 403
 404 <DL COMPACT>
 405
 406 <DT><SAMP>`<VAR>inputfile</VAR>&acute;</SAMP>
 407 <DD>
 408 Input PO file.
 409
 410 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
 411 <DD>
 412 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
 413 <DD>
 414 <A NAME="IDX540"></A>
 415 <A NAME="IDX541"></A>
 416 Add <VAR>directory</VAR> to the list of directories.  Source files are
 417 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
 418 file will be written relative to the current directory, though.
 419
 420 </DL>
 421
 422 <P>
 423 If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-&acute;</SAMP>, standard input is read.
 424
 425 </P>
 426
 427
 428 <H3><A NAME="SEC76" HREF="gettext_toc.html#TOC76">7.2.2  Output file location</A></H3>
 429
 430 <DL COMPACT>
 431
 432 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
 433 <DD>
 434 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
 435 <DD>
 436 <A NAME="IDX542"></A>
 437 <A NAME="IDX543"></A>
 438 Write output to specified file.
 439
 440 </DL>
 441
 442 <P>
 443 The results are written to standard output if no output file is specified
 444 or if it is <SAMP>`-&acute;</SAMP>.
 445
 446 </P>
 447
 448
 449 <H3><A NAME="SEC77" HREF="gettext_toc.html#TOC77">7.2.3  Conversion target</A></H3>
 450
 451 <DL COMPACT>
 452
 453 <DT><SAMP>`-t&acute;</SAMP>
 454 <DD>
 455 <DT><SAMP>`--to-code=<VAR>name</VAR>&acute;</SAMP>
 456 <DD>
 457 <A NAME="IDX544"></A>
 458 <A NAME="IDX545"></A>
 459 Specify encoding for output.
 460
 461 </DL>
 462
 463 <P>
 464 The default encoding is the current locale's encoding.
 465
 466 </P>
 467
 468
 469 <H3><A NAME="SEC78" HREF="gettext_toc.html#TOC78">7.2.4  Input file syntax</A></H3>
 470
 471 <DL COMPACT>
 472
 473 <DT><SAMP>`-P&acute;</SAMP>
 474 <DD>
 475 <DT><SAMP>`--properties-input&acute;</SAMP>
 476 <DD>
 477 <A NAME="IDX546"></A>
 478 <A NAME="IDX547"></A>
 479 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
 480 syntax, not in PO file syntax.
 481
 482 <DT><SAMP>`--stringtable-input&acute;</SAMP>
 483 <DD>
 484 <A NAME="IDX548"></A>
 485 Assume the input file is a NeXTstep/GNUstep localized resource file in
 486 <CODE>.strings</CODE> syntax, not in PO file syntax.
 487
 488 </DL>
 489
 490
 491
 492 <H3><A NAME="SEC79" HREF="gettext_toc.html#TOC79">7.2.5  Output details</A></H3>
 493
 494 <DL COMPACT>
 495
 496 <DT><SAMP>`--force-po&acute;</SAMP>
 497 <DD>
 498 <A NAME="IDX549"></A>
 499 Always write an output file even if it contains no message.
 500
 501 <DT><SAMP>`-i&acute;</SAMP>
 502 <DD>
 503 <DT><SAMP>`--indent&acute;</SAMP>
 504 <DD>
 505 <A NAME="IDX550"></A>
 506 <A NAME="IDX551"></A>
 507 Write the .po file using indented style.
 508
 509 <DT><SAMP>`--no-location&acute;</SAMP>
 510 <DD>
 511 <A NAME="IDX552"></A>
 512 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
 513
 514 <DT><SAMP>`--add-location&acute;</SAMP>
 515 <DD>
 516 <A NAME="IDX553"></A>
 517 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
 518
 519 <DT><SAMP>`--strict&acute;</SAMP>
 520 <DD>
 521 <A NAME="IDX554"></A>
 522 Write out a strict Uniforum conforming PO file.  Note that this
 523 Uniforum format should be avoided because it doesn't support the
 524 GNU extensions.
 525
 526 <DT><SAMP>`-p&acute;</SAMP>
 527 <DD>
 528 <DT><SAMP>`--properties-output&acute;</SAMP>
 529 <DD>
 530 <A NAME="IDX555"></A>
 531 <A NAME="IDX556"></A>
 532 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
 533 that this file format doesn't support plural forms and silently drops
 534 obsolete messages.
 535
 536 <DT><SAMP>`--stringtable-output&acute;</SAMP>
 537 <DD>
 538 <A NAME="IDX557"></A>
 539 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
 540 Note that this file format doesn't support plural forms.
 541
 542 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
 543 <DD>
 544 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
 545 <DD>
 546 <A NAME="IDX558"></A>
 547 <A NAME="IDX559"></A>
 548 Set the output page width.  Long strings in the output files will be
 549 split across multiple lines in order to ensure that each line's width
 550 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
 551
 552 <DT><SAMP>`--no-wrap&acute;</SAMP>
 553 <DD>
 554 <A NAME="IDX560"></A>
 555 Do not break long message lines.  Message lines whose width exceeds the
 556 output page width will not be split into several lines.  Only file reference
 557 lines which are wider than the output page width will be split.
 558
 559 <DT><SAMP>`-s&acute;</SAMP>
 560 <DD>
 561 <DT><SAMP>`--sort-output&acute;</SAMP>
 562 <DD>
 563 <A NAME="IDX561"></A>
 564 <A NAME="IDX562"></A>
 565 Generate sorted output.  Note that using this option makes it much harder
 566 for the translator to understand each message's context.
 567
 568 <DT><SAMP>`-F&acute;</SAMP>
 569 <DD>
 570 <DT><SAMP>`--sort-by-file&acute;</SAMP>
 571 <DD>
 572 <A NAME="IDX563"></A>
 573 <A NAME="IDX564"></A>
 574 Sort output by file location.
 575
 576 </DL>
 577
 578
 579
 580 <H3><A NAME="SEC80" HREF="gettext_toc.html#TOC80">7.2.6  Informative output</A></H3>
 581
 582 <DL COMPACT>
 583
 584 <DT><SAMP>`-h&acute;</SAMP>
 585 <DD>
 586 <DT><SAMP>`--help&acute;</SAMP>
 587 <DD>
 588 <A NAME="IDX565"></A>
 589 <A NAME="IDX566"></A>
 590 Display this help and exit.
 591
 592 <DT><SAMP>`-V&acute;</SAMP>
 593 <DD>
 594 <DT><SAMP>`--version&acute;</SAMP>
 595 <DD>
 596 <A NAME="IDX567"></A>
 597 <A NAME="IDX568"></A>
 598 Output version information and exit.
 599
 600 </DL>
 601
 602
 603
 604 <H2><A NAME="SEC81" HREF="gettext_toc.html#TOC81">7.3  Invoking the <CODE>msggrep</CODE> Program</A></H2>
 605
 606 <P>
 607 <A NAME="IDX569"></A>
 608 <A NAME="IDX570"></A>
 609
 610 <PRE>
 611 msggrep [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
 612 </PRE>
 613
 614 <P>
 615 <A NAME="IDX571"></A>
 616 The <CODE>msggrep</CODE> program extracts all messages of a translation catalog
 617 that match a given pattern or belong to some given source files.
 618
 619 </P>
 620
 621
 622 <H3><A NAME="SEC82" HREF="gettext_toc.html#TOC82">7.3.1  Input file location</A></H3>
 623
 624 <DL COMPACT>
 625
 626 <DT><SAMP>`<VAR>inputfile</VAR>&acute;</SAMP>
 627 <DD>
 628 Input PO file.
 629
 630 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
 631 <DD>
 632 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
 633 <DD>
 634 <A NAME="IDX572"></A>
 635 <A NAME="IDX573"></A>
 636 Add <VAR>directory</VAR> to the list of directories.  Source files are
 637 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
 638 file will be written relative to the current directory, though.
 639
 640 </DL>
 641
 642 <P>
 643 If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-&acute;</SAMP>, standard input is read.
 644
 645 </P>
 646
 647
 648 <H3><A NAME="SEC83" HREF="gettext_toc.html#TOC83">7.3.2  Output file location</A></H3>
 649
 650 <DL COMPACT>
 651
 652 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
 653 <DD>
 654 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
 655 <DD>
 656 <A NAME="IDX574"></A>
 657 <A NAME="IDX575"></A>
 658 Write output to specified file.
 659
 660 </DL>
 661
 662 <P>
 663 The results are written to standard output if no output file is specified
 664 or if it is <SAMP>`-&acute;</SAMP>.
 665
 666 </P>
 667
 668
 669 <H3><A NAME="SEC84" HREF="gettext_toc.html#TOC84">7.3.3  Message selection</A></H3>
 670
 671
 672 <PRE>
 673   [-N <VAR>sourcefile</VAR>]... [-M <VAR>domainname</VAR>]...
 674   [-K <VAR>msgid-pattern</VAR>] [-T <VAR>msgstr-pattern</VAR>] [-C <VAR>comment-pattern</VAR>]
 675 </PRE>
 676
 677 <P>
 678 A message is selected if
 679
 680 <UL>
 681 <LI>it comes from one of the specified source files,
 682
 683 <LI>or if it comes from one of the specified domains,
 684
 685 <LI>or if <SAMP>`-K&acute;</SAMP> is given and its key (msgid or msgid_plural) matches
 686
 687       <VAR>msgid-pattern</VAR>,
 688 <LI>or if <SAMP>`-T&acute;</SAMP> is given and its translation (msgstr) matches
 689
 690       <VAR>msgstr-pattern</VAR>,
 691 <LI>or if <SAMP>`-C&acute;</SAMP> is given and the translator's comment matches
 692
 693       <VAR>comment-pattern</VAR>.
 694 </UL>
 695
 696 <P>
 697 When more than one selection criterion is specified, the set of selected
 698 messages is the union of the selected messages of each criterion.
 699
 700 </P>
 701 <P>
 702 <VAR>msgid-pattern</VAR> or <VAR>msgstr-pattern</VAR> syntax:
 703
 704 <PRE>
 705   [-E | -F] [-e <VAR>pattern</VAR> | -f <VAR>file</VAR>]...
 706 </PRE>
 707
 708 <P>
 709 <VAR>pattern</VAR>s are basic regular expressions by default, or extended regular
 710 expressions if -E is given, or fixed strings if -F is given.
 711
 712 </P>
 713 <DL COMPACT>
 714
 715 <DT><SAMP>`-N <VAR>sourcefile</VAR>&acute;</SAMP>
 716 <DD>
 717 <DT><SAMP>`--location=<VAR>sourcefile</VAR>&acute;</SAMP>
 718 <DD>
 719 <A NAME="IDX576"></A>
 720 <A NAME="IDX577"></A>
 721 Select messages extracted from <VAR>sourcefile</VAR>.  <VAR>sourcefile</VAR> can be
 722 either a literal file name or a wildcard pattern.
 723
 724 <DT><SAMP>`-M <VAR>domainname</VAR>&acute;</SAMP>
 725 <DD>
 726 <DT><SAMP>`--domain=<VAR>domainname</VAR>&acute;</SAMP>
 727 <DD>
 728 <A NAME="IDX578"></A>
 729 <A NAME="IDX579"></A>
 730 Select messages belonging to domain <VAR>domainname</VAR>.
 731
 732 <DT><SAMP>`-K&acute;</SAMP>
 733 <DD>
 734 <DT><SAMP>`--msgid&acute;</SAMP>
 735 <DD>
 736 <A NAME="IDX580"></A>
 737 <A NAME="IDX581"></A>
 738 Start of patterns for the msgid.
 739
 740 <DT><SAMP>`-T&acute;</SAMP>
 741 <DD>
 742 <DT><SAMP>`--msgstr&acute;</SAMP>
 743 <DD>
 744 <A NAME="IDX582"></A>
 745 <A NAME="IDX583"></A>
 746 Start of patterns for the msgstr.
 747
 748 <DT><SAMP>`-C&acute;</SAMP>
 749 <DD>
 750 <DT><SAMP>`--comment&acute;</SAMP>
 751 <DD>
 752 <A NAME="IDX584"></A>
 753 <A NAME="IDX585"></A>
 754 Start of patterns for the translator's comment.
 755
 756 <DT><SAMP>`-E&acute;</SAMP>
 757 <DD>
 758 <DT><SAMP>`--extended-regexp&acute;</SAMP>
 759 <DD>
 760 <A NAME="IDX586"></A>
 761 <A NAME="IDX587"></A>
 762 Specify that <VAR>pattern</VAR> is an extended regular expression.
 763
 764 <DT><SAMP>`-F&acute;</SAMP>
 765 <DD>
 766 <DT><SAMP>`--fixed-strings&acute;</SAMP>
 767 <DD>
 768 <A NAME="IDX588"></A>
 769 <A NAME="IDX589"></A>
 770 Specify that <VAR>pattern</VAR> is a set of newline-separated strings.
 771
 772 <DT><SAMP>`-e <VAR>pattern</VAR>&acute;</SAMP>
 773 <DD>
 774 <DT><SAMP>`--regexp=<VAR>pattern</VAR>&acute;</SAMP>
 775 <DD>
 776 <A NAME="IDX590"></A>
 777 <A NAME="IDX591"></A>
 778 Use <VAR>pattern</VAR> as a regular expression.
 779
 780 <DT><SAMP>`-f <VAR>file</VAR>&acute;</SAMP>
 781 <DD>
 782 <DT><SAMP>`--file=<VAR>file</VAR>&acute;</SAMP>
 783 <DD>
 784 <A NAME="IDX592"></A>
 785 <A NAME="IDX593"></A>
 786 Obtain <VAR>pattern</VAR> from <VAR>file</VAR>.
 787
 788 <DT><SAMP>`-i&acute;</SAMP>
 789 <DD>
 790 <DT><SAMP>`--ignore-case&acute;</SAMP>
 791 <DD>
 792 <A NAME="IDX594"></A>
 793 <A NAME="IDX595"></A>
 794 Ignore case distinctions.
 795
 796 </DL>
 797
 798
 799
 800 <H3><A NAME="SEC85" HREF="gettext_toc.html#TOC85">7.3.4  Input file syntax</A></H3>
 801
 802 <DL COMPACT>
 803
 804 <DT><SAMP>`-P&acute;</SAMP>
 805 <DD>
 806 <DT><SAMP>`--properties-input&acute;</SAMP>
 807 <DD>
 808 <A NAME="IDX596"></A>
 809 <A NAME="IDX597"></A>
 810 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
 811 syntax, not in PO file syntax.
 812
 813 <DT><SAMP>`--stringtable-input&acute;</SAMP>
 814 <DD>
 815 <A NAME="IDX598"></A>
 816 Assume the input file is a NeXTstep/GNUstep localized resource file in
 817 <CODE>.strings</CODE> syntax, not in PO file syntax.
 818
 819 </DL>
 820
 821
 822
 823 <H3><A NAME="SEC86" HREF="gettext_toc.html#TOC86">7.3.5  Output details</A></H3>
 824
 825 <DL COMPACT>
 826
 827 <DT><SAMP>`--force-po&acute;</SAMP>
 828 <DD>
 829 <A NAME="IDX599"></A>
 830 Always write an output file even if it contains no message.
 831
 832 <DT><SAMP>`--indent&acute;</SAMP>
 833 <DD>
 834 <A NAME="IDX600"></A>
 835 Write the .po file using indented style.
 836
 837 <DT><SAMP>`--no-location&acute;</SAMP>
 838 <DD>
 839 <A NAME="IDX601"></A>
 840 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
 841
 842 <DT><SAMP>`--add-location&acute;</SAMP>
 843 <DD>
 844 <A NAME="IDX602"></A>
 845 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
 846
 847 <DT><SAMP>`--strict&acute;</SAMP>
 848 <DD>
 849 <A NAME="IDX603"></A>
 850 Write out a strict Uniforum conforming PO file.  Note that this
 851 Uniforum format should be avoided because it doesn't support the
 852 GNU extensions.
 853
 854 <DT><SAMP>`-p&acute;</SAMP>
 855 <DD>
 856 <DT><SAMP>`--properties-output&acute;</SAMP>
 857 <DD>
 858 <A NAME="IDX604"></A>
 859 <A NAME="IDX605"></A>
 860 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
 861 that this file format doesn't support plural forms and silently drops
 862 obsolete messages.
 863
 864 <DT><SAMP>`--stringtable-output&acute;</SAMP>
 865 <DD>
 866 <A NAME="IDX606"></A>
 867 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
 868 Note that this file format doesn't support plural forms.
 869
 870 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
 871 <DD>
 872 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
 873 <DD>
 874 <A NAME="IDX607"></A>
 875 <A NAME="IDX608"></A>
 876 Set the output page width.  Long strings in the output files will be
 877 split across multiple lines in order to ensure that each line's width
 878 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
 879
 880 <DT><SAMP>`--no-wrap&acute;</SAMP>
 881 <DD>
 882 <A NAME="IDX609"></A>
 883 Do not break long message lines.  Message lines whose width exceeds the
 884 output page width will not be split into several lines.  Only file reference
 885 lines which are wider than the output page width will be split.
 886
 887 <DT><SAMP>`--sort-output&acute;</SAMP>
 888 <DD>
 889 <A NAME="IDX610"></A>
 890 Generate sorted output.  Note that using this option makes it much harder
 891 for the translator to understand each message's context.
 892
 893 <DT><SAMP>`--sort-by-file&acute;</SAMP>
 894 <DD>
 895 <A NAME="IDX611"></A>
 896 Sort output by file location.
 897
 898 </DL>
 899
 900
 901
 902 <H3><A NAME="SEC87" HREF="gettext_toc.html#TOC87">7.3.6  Informative output</A></H3>
 903
 904 <DL COMPACT>
 905
 906 <DT><SAMP>`-h&acute;</SAMP>
 907 <DD>
 908 <DT><SAMP>`--help&acute;</SAMP>
 909 <DD>
 910 <A NAME="IDX612"></A>
 911 <A NAME="IDX613"></A>
 912 Display this help and exit.
 913
 914 <DT><SAMP>`-V&acute;</SAMP>
 915 <DD>
 916 <DT><SAMP>`--version&acute;</SAMP>
 917 <DD>
 918 <A NAME="IDX614"></A>
 919 <A NAME="IDX615"></A>
 920 Output version information and exit.
 921
 922 </DL>
 923
 924
 925
 926 <H2><A NAME="SEC88" HREF="gettext_toc.html#TOC88">7.4  Invoking the <CODE>msgfilter</CODE> Program</A></H2>
 927
 928 <P>
 929 <A NAME="IDX616"></A>
 930 <A NAME="IDX617"></A>
 931
 932 <PRE>
 933 msgfilter [<VAR>option</VAR>] <VAR>filter</VAR> [<VAR>filter-option</VAR>]
 934 </PRE>
 935
 936 <P>
 937 <A NAME="IDX618"></A>
 938 The <CODE>msgfilter</CODE> program applies a filter to all translations of a
 939 translation catalog.
 940
 941 </P>
 942
 943
 944 <H3><A NAME="SEC89" HREF="gettext_toc.html#TOC89">7.4.1  Input file location</A></H3>
 945
 946 <DL COMPACT>
 947
 948 <DT><SAMP>`-i <VAR>inputfile</VAR>&acute;</SAMP>
 949 <DD>
 950 <DT><SAMP>`--input=<VAR>inputfile</VAR>&acute;</SAMP>
 951 <DD>
 952 <A NAME="IDX619"></A>
 953 <A NAME="IDX620"></A>
 954 Input PO file.
 955
 956 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
 957 <DD>
 958 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
 959 <DD>
 960 <A NAME="IDX621"></A>
 961 <A NAME="IDX622"></A>
 962 Add <VAR>directory</VAR> to the list of directories.  Source files are
 963 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
 964 file will be written relative to the current directory, though.
 965
 966 </DL>
 967
 968 <P>
 969 If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-&acute;</SAMP>, standard input is read.
 970
 971 </P>
 972
 973
 974 <H3><A NAME="SEC90" HREF="gettext_toc.html#TOC90">7.4.2  Output file location</A></H3>
 975
 976 <DL COMPACT>
 977
 978 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
 979 <DD>
 980 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
 981 <DD>
 982 <A NAME="IDX623"></A>
 983 <A NAME="IDX624"></A>
 984 Write output to specified file.
 985
 986 </DL>
 987
 988 <P>
 989 The results are written to standard output if no output file is specified
 990 or if it is <SAMP>`-&acute;</SAMP>.
 991
 992 </P>
 993
 994
 995 <H3><A NAME="SEC91" HREF="gettext_toc.html#TOC91">7.4.3  The filter</A></H3>
 996
 997 <P>
 998 The <VAR>filter</VAR> can be any program that reads a translation from standard
 999 input and writes a modified translation to standard output.  A frequently
1000 used filter is <SAMP>`sed&acute;</SAMP>.
1001
1002 </P>
1003 <P>
1004 <A NAME="IDX625"></A>
1005 Note: It is your responsibility to ensure that the <VAR>filter</VAR> can cope
1006 with input encoded in the translation catalog's encoding.  If the
1007 <VAR>filter</VAR> wants input in a particular encoding, you can in a first step
1008 convert the translation catalog to that encoding using the <SAMP>`msgconv&acute;</SAMP>
1009 program, before invoking <SAMP>`msgfilter&acute;</SAMP>.  If the <VAR>filter</VAR> wants input
1010 in the locale's encoding, but you want to avoid the locale's encoding, then
1011 you can first convert the translation catalog to UTF-8 using the
1012 <SAMP>`msgconv&acute;</SAMP> program and then make <SAMP>`msgfilter&acute;</SAMP> work in an UTF-8
1013 locale, by using the <CODE>LC_ALL</CODE> environment variable.
1014
1015 </P>
1016 <P>
1017 <A NAME="IDX626"></A>
1018 Note: Most translations in a translation catalog don't end with a newline
1019 character.  For this reason, it is important that the <VAR>filter</VAR>
1020 recognizes its last input line even if it ends without a newline, and that
1021 it doesn't add an undesired trailing newline at the end.  The <SAMP>`sed&acute;</SAMP>
1022 program on some platforms is known to ignore the last line of input if it
1023 is not terminated with a newline.  You can use GNU <CODE>sed</CODE> instead; it
1024 does not have this limitation.
1025
1026 </P>
1027
1028
1029 <H3><A NAME="SEC92" HREF="gettext_toc.html#TOC92">7.4.4  Useful <VAR>filter-option</VAR>s when the <VAR>filter</VAR> is <SAMP>`sed&acute;</SAMP></A></H3>
1030
1031 <DL COMPACT>
1032
1033 <DT><SAMP>`-e <VAR>script</VAR>&acute;</SAMP>
1034 <DD>
1035 <DT><SAMP>`--expression=<VAR>script</VAR>&acute;</SAMP>
1036 <DD>
1037 <A NAME="IDX627"></A>
1038 <A NAME="IDX628"></A>
1039 Add <VAR>script</VAR> to the commands to be executed.
1040
1041 <DT><SAMP>`-f <VAR>scriptfile</VAR>&acute;</SAMP>
1042 <DD>
1043 <DT><SAMP>`--file=<VAR>scriptfile</VAR>&acute;</SAMP>
1044 <DD>
1045 <A NAME="IDX629"></A>
1046 <A NAME="IDX630"></A>
1047 Add the contents of <VAR>scriptfile</VAR> to the commands to be executed.
1048
1049 <DT><SAMP>`-n&acute;</SAMP>
1050 <DD>
1051 <DT><SAMP>`--quiet&acute;</SAMP>
1052 <DD>
1053 <DT><SAMP>`--silent&acute;</SAMP>
1054 <DD>
1055 <A NAME="IDX631"></A>
1056 <A NAME="IDX632"></A>
1057 <A NAME="IDX633"></A>
1058 Suppress automatic printing of pattern space.
1059
1060 </DL>
1061
1062
1063
1064 <H3><A NAME="SEC93" HREF="gettext_toc.html#TOC93">7.4.5  Input file syntax</A></H3>
1065
1066 <DL COMPACT>
1067
1068 <DT><SAMP>`-P&acute;</SAMP>
1069 <DD>
1070 <DT><SAMP>`--properties-input&acute;</SAMP>
1071 <DD>
1072 <A NAME="IDX634"></A>
1073 <A NAME="IDX635"></A>
1074 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
1075 syntax, not in PO file syntax.
1076
1077 <DT><SAMP>`--stringtable-input&acute;</SAMP>
1078 <DD>
1079 <A NAME="IDX636"></A>
1080 Assume the input file is a NeXTstep/GNUstep localized resource file in
1081 <CODE>.strings</CODE> syntax, not in PO file syntax.
1082
1083 </DL>
1084
1085
1086
1087 <H3><A NAME="SEC94" HREF="gettext_toc.html#TOC94">7.4.6  Output details</A></H3>
1088
1089 <DL COMPACT>
1090
1091 <DT><SAMP>`--force-po&acute;</SAMP>
1092 <DD>
1093 <A NAME="IDX637"></A>
1094 Always write an output file even if it contains no message.
1095
1096 <DT><SAMP>`--indent&acute;</SAMP>
1097 <DD>
1098 <A NAME="IDX638"></A>
1099 Write the .po file using indented style.
1100
1101 <DT><SAMP>`--keep-header&acute;</SAMP>
1102 <DD>
1103 <A NAME="IDX639"></A>
1104 Keep the header entry, i.e. the message with <SAMP>`msgid ""&acute;</SAMP>, unmodified,
1105 instead of filtering it.  By default, the header entry is subject to
1106 filtering like any other message.
1107
1108 <DT><SAMP>`--no-location&acute;</SAMP>
1109 <DD>
1110 <A NAME="IDX640"></A>
1111 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
1112
1113 <DT><SAMP>`--add-location&acute;</SAMP>
1114 <DD>
1115 <A NAME="IDX641"></A>
1116 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
1117
1118 <DT><SAMP>`--strict&acute;</SAMP>
1119 <DD>
1120 <A NAME="IDX642"></A>
1121 Write out a strict Uniforum conforming PO file.  Note that this
1122 Uniforum format should be avoided because it doesn't support the
1123 GNU extensions.
1124
1125 <DT><SAMP>`-p&acute;</SAMP>
1126 <DD>
1127 <DT><SAMP>`--properties-output&acute;</SAMP>
1128 <DD>
1129 <A NAME="IDX643"></A>
1130 <A NAME="IDX644"></A>
1131 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
1132 that this file format doesn't support plural forms and silently drops
1133 obsolete messages.
1134
1135 <DT><SAMP>`--stringtable-output&acute;</SAMP>
1136 <DD>
1137 <A NAME="IDX645"></A>
1138 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
1139 Note that this file format doesn't support plural forms.
1140
1141 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
1142 <DD>
1143 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
1144 <DD>
1145 <A NAME="IDX646"></A>
1146 <A NAME="IDX647"></A>
1147 Set the output page width.  Long strings in the output files will be
1148 split across multiple lines in order to ensure that each line's width
1149 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
1150
1151 <DT><SAMP>`--no-wrap&acute;</SAMP>
1152 <DD>
1153 <A NAME="IDX648"></A>
1154 Do not break long message lines.  Message lines whose width exceeds the
1155 output page width will not be split into several lines.  Only file reference
1156 lines which are wider than the output page width will be split.
1157
1158 <DT><SAMP>`-s&acute;</SAMP>
1159 <DD>
1160 <DT><SAMP>`--sort-output&acute;</SAMP>
1161 <DD>
1162 <A NAME="IDX649"></A>
1163 <A NAME="IDX650"></A>
1164 Generate sorted output.  Note that using this option makes it much harder
1165 for the translator to understand each message's context.
1166
1167 <DT><SAMP>`-F&acute;</SAMP>
1168 <DD>
1169 <DT><SAMP>`--sort-by-file&acute;</SAMP>
1170 <DD>
1171 <A NAME="IDX651"></A>
1172 <A NAME="IDX652"></A>
1173 Sort output by file location.
1174
1175 </DL>
1176
1177
1178
1179 <H3><A NAME="SEC95" HREF="gettext_toc.html#TOC95">7.4.7  Informative output</A></H3>
1180
1181 <DL COMPACT>
1182
1183 <DT><SAMP>`-h&acute;</SAMP>
1184 <DD>
1185 <DT><SAMP>`--help&acute;</SAMP>
1186 <DD>
1187 <A NAME="IDX653"></A>
1188 <A NAME="IDX654"></A>
1189 Display this help and exit.
1190
1191 <DT><SAMP>`-V&acute;</SAMP>
1192 <DD>
1193 <DT><SAMP>`--version&acute;</SAMP>
1194 <DD>
1195 <A NAME="IDX655"></A>
1196 <A NAME="IDX656"></A>
1197 Output version information and exit.
1198
1199 </DL>
1200
1201
1202
1203 <H2><A NAME="SEC96" HREF="gettext_toc.html#TOC96">7.5  Invoking the <CODE>msguniq</CODE> Program</A></H2>
1204
1205 <P>
1206 <A NAME="IDX657"></A>
1207 <A NAME="IDX658"></A>
1208
1209 <PRE>
1210 msguniq [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
1211 </PRE>
1212
1213 <P>
1214 <A NAME="IDX659"></A>
1215 <A NAME="IDX660"></A>
1216 The <CODE>msguniq</CODE> program unifies duplicate translations in a translation
1217 catalog.  It finds duplicate translations of the same message ID.  Such
1218 duplicates are invalid input for other programs like <CODE>msgfmt</CODE>,
1219 <CODE>msgmerge</CODE> or <CODE>msgcat</CODE>.  By default, duplicates are merged
1220 together.  When using the <SAMP>`--repeated&acute;</SAMP> option, only duplicates are
1221 output, and all other messages are discarded.  Comments and extracted
1222 comments will be cumulated, except that if <SAMP>`--use-first&acute;</SAMP> is
1223 specified, they will be taken from the first translation.  File positions
1224 will be cumulated.  When using the <SAMP>`--unique&acute;</SAMP> option, duplicates are
1225 discarded.
1226
1227 </P>
1228
1229
1230 <H3><A NAME="SEC97" HREF="gettext_toc.html#TOC97">7.5.1  Input file location</A></H3>
1231
1232 <DL COMPACT>
1233
1234 <DT><SAMP>`<VAR>inputfile</VAR>&acute;</SAMP>
1235 <DD>
1236 Input PO file.
1237
1238 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
1239 <DD>
1240 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
1241 <DD>
1242 <A NAME="IDX661"></A>
1243 <A NAME="IDX662"></A>
1244 Add <VAR>directory</VAR> to the list of directories.  Source files are
1245 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
1246 file will be written relative to the current directory, though.
1247
1248 </DL>
1249
1250 <P>
1251 If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-&acute;</SAMP>, standard input is read.
1252
1253 </P>
1254
1255
1256 <H3><A NAME="SEC98" HREF="gettext_toc.html#TOC98">7.5.2  Output file location</A></H3>
1257
1258 <DL COMPACT>
1259
1260 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
1261 <DD>
1262 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
1263 <DD>
1264 <A NAME="IDX663"></A>
1265 <A NAME="IDX664"></A>
1266 Write output to specified file.
1267
1268 </DL>
1269
1270 <P>
1271 The results are written to standard output if no output file is specified
1272 or if it is <SAMP>`-&acute;</SAMP>.
1273
1274 </P>
1275
1276
1277 <H3><A NAME="SEC99" HREF="gettext_toc.html#TOC99">7.5.3  Message selection</A></H3>
1278
1279 <DL COMPACT>
1280
1281 <DT><SAMP>`-d&acute;</SAMP>
1282 <DD>
1283 <DT><SAMP>`--repeated&acute;</SAMP>
1284 <DD>
1285 <A NAME="IDX665"></A>
1286 <A NAME="IDX666"></A>
1287 Print only duplicates.
1288
1289 <DT><SAMP>`-u&acute;</SAMP>
1290 <DD>
1291 <DT><SAMP>`--unique&acute;</SAMP>
1292 <DD>
1293 <A NAME="IDX667"></A>
1294 <A NAME="IDX668"></A>
1295 Print only unique messages, discard duplicates.
1296
1297 </DL>
1298
1299
1300
1301 <H3><A NAME="SEC100" HREF="gettext_toc.html#TOC100">7.5.4  Input file syntax</A></H3>
1302
1303 <DL COMPACT>
1304
1305 <DT><SAMP>`-P&acute;</SAMP>
1306 <DD>
1307 <DT><SAMP>`--properties-input&acute;</SAMP>
1308 <DD>
1309 <A NAME="IDX669"></A>
1310 <A NAME="IDX670"></A>
1311 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
1312 syntax, not in PO file syntax.
1313
1314 <DT><SAMP>`--stringtable-input&acute;</SAMP>
1315 <DD>
1316 <A NAME="IDX671"></A>
1317 Assume the input file is a NeXTstep/GNUstep localized resource file in
1318 <CODE>.strings</CODE> syntax, not in PO file syntax.
1319
1320 </DL>
1321
1322
1323
1324 <H3><A NAME="SEC101" HREF="gettext_toc.html#TOC101">7.5.5  Output details</A></H3>
1325
1326 <DL COMPACT>
1327
1328 <DT><SAMP>`-t&acute;</SAMP>
1329 <DD>
1330 <DT><SAMP>`--to-code=<VAR>name</VAR>&acute;</SAMP>
1331 <DD>
1332 <A NAME="IDX672"></A>
1333 <A NAME="IDX673"></A>
1334 Specify encoding for output.
1335
1336 <DT><SAMP>`--use-first&acute;</SAMP>
1337 <DD>
1338 <A NAME="IDX674"></A>
1339 Use first available translation for each message.  Don't merge several
1340 translations into one.
1341
1342 <DT><SAMP>`--force-po&acute;</SAMP>
1343 <DD>
1344 <A NAME="IDX675"></A>
1345 Always write an output file even if it contains no message.
1346
1347 <DT><SAMP>`-i&acute;</SAMP>
1348 <DD>
1349 <DT><SAMP>`--indent&acute;</SAMP>
1350 <DD>
1351 <A NAME="IDX676"></A>
1352 <A NAME="IDX677"></A>
1353 Write the .po file using indented style.
1354
1355 <DT><SAMP>`--no-location&acute;</SAMP>
1356 <DD>
1357 <A NAME="IDX678"></A>
1358 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
1359
1360 <DT><SAMP>`-n&acute;</SAMP>
1361 <DD>
1362 <DT><SAMP>`--add-location&acute;</SAMP>
1363 <DD>
1364 <A NAME="IDX679"></A>
1365 <A NAME="IDX680"></A>
1366 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
1367
1368 <DT><SAMP>`--strict&acute;</SAMP>
1369 <DD>
1370 <A NAME="IDX681"></A>
1371 Write out a strict Uniforum conforming PO file.  Note that this
1372 Uniforum format should be avoided because it doesn't support the
1373 GNU extensions.
1374
1375 <DT><SAMP>`-p&acute;</SAMP>
1376 <DD>
1377 <DT><SAMP>`--properties-output&acute;</SAMP>
1378 <DD>
1379 <A NAME="IDX682"></A>
1380 <A NAME="IDX683"></A>
1381 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
1382 that this file format doesn't support plural forms and silently drops
1383 obsolete messages.
1384
1385 <DT><SAMP>`--stringtable-output&acute;</SAMP>
1386 <DD>
1387 <A NAME="IDX684"></A>
1388 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
1389 Note that this file format doesn't support plural forms.
1390
1391 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
1392 <DD>
1393 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
1394 <DD>
1395 <A NAME="IDX685"></A>
1396 <A NAME="IDX686"></A>
1397 Set the output page width.  Long strings in the output files will be
1398 split across multiple lines in order to ensure that each line's width
1399 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
1400
1401 <DT><SAMP>`--no-wrap&acute;</SAMP>
1402 <DD>
1403 <A NAME="IDX687"></A>
1404 Do not break long message lines.  Message lines whose width exceeds the
1405 output page width will not be split into several lines.  Only file reference
1406 lines which are wider than the output page width will be split.
1407
1408 <DT><SAMP>`-s&acute;</SAMP>
1409 <DD>
1410 <DT><SAMP>`--sort-output&acute;</SAMP>
1411 <DD>
1412 <A NAME="IDX688"></A>
1413 <A NAME="IDX689"></A>
1414 Generate sorted output.  Note that using this option makes it much harder
1415 for the translator to understand each message's context.
1416
1417 <DT><SAMP>`-F&acute;</SAMP>
1418 <DD>
1419 <DT><SAMP>`--sort-by-file&acute;</SAMP>
1420 <DD>
1421 <A NAME="IDX690"></A>
1422 <A NAME="IDX691"></A>
1423 Sort output by file location.
1424
1425 </DL>
1426
1427
1428
1429 <H3><A NAME="SEC102" HREF="gettext_toc.html#TOC102">7.5.6  Informative output</A></H3>
1430
1431 <DL COMPACT>
1432
1433 <DT><SAMP>`-h&acute;</SAMP>
1434 <DD>
1435 <DT><SAMP>`--help&acute;</SAMP>
1436 <DD>
1437 <A NAME="IDX692"></A>
1438 <A NAME="IDX693"></A>
1439 Display this help and exit.
1440
1441 <DT><SAMP>`-V&acute;</SAMP>
1442 <DD>
1443 <DT><SAMP>`--version&acute;</SAMP>
1444 <DD>
1445 <A NAME="IDX694"></A>
1446 <A NAME="IDX695"></A>
1447 Output version information and exit.
1448
1449 </DL>
1450
1451
1452
1453 <H2><A NAME="SEC103" HREF="gettext_toc.html#TOC103">7.6  Invoking the <CODE>msgcomm</CODE> Program</A></H2>
1454
1455 <P>
1456 <A NAME="IDX696"></A>
1457 <A NAME="IDX697"></A>
1458
1459 <PRE>
1460 msgcomm [<VAR>option</VAR>] [<VAR>inputfile</VAR>]...
1461 </PRE>
1462
1463 <P>
1464 <A NAME="IDX698"></A>
1465 The <CODE>msgcomm</CODE> program finds messages which are common to two or more
1466 of the specified PO files.
1467 By using the <CODE>--more-than</CODE> option, greater commonality may be requested
1468 before messages are printed.  Conversely, the <CODE>--less-than</CODE> option may be
1469 used to specify less commonality before messages are printed (i.e.
1470 <SAMP>`--less-than=2&acute;</SAMP> will only print the unique messages).  Translations,
1471 comments and extract comments will be preserved, but only from the first
1472 PO file to define them.  File positions from all PO files will be
1473 cumulated.
1474
1475 </P>
1476
1477
1478 <H3><A NAME="SEC104" HREF="gettext_toc.html#TOC104">7.6.1  Input file location</A></H3>
1479
1480 <DL COMPACT>
1481
1482 <DT><SAMP>`<VAR>inputfile</VAR> ...&acute;</SAMP>
1483 <DD>
1484 Input files.
1485
1486 <DT><SAMP>`-f <VAR>file</VAR>&acute;</SAMP>
1487 <DD>
1488 <DT><SAMP>`--files-from=<VAR>file</VAR>&acute;</SAMP>
1489 <DD>
1490 <A NAME="IDX699"></A>
1491 <A NAME="IDX700"></A>
1492 Read the names of the input files from <VAR>file</VAR> instead of getting
1493 them from the command line.
1494
1495 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
1496 <DD>
1497 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
1498 <DD>
1499 <A NAME="IDX701"></A>
1500 <A NAME="IDX702"></A>
1501 Add <VAR>directory</VAR> to the list of directories.  Source files are
1502 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
1503 file will be written relative to the current directory, though.
1504
1505 </DL>
1506
1507 <P>
1508 If <VAR>inputfile</VAR> is <SAMP>`-&acute;</SAMP>, standard input is read.
1509
1510 </P>
1511
1512
1513 <H3><A NAME="SEC105" HREF="gettext_toc.html#TOC105">7.6.2  Output file location</A></H3>
1514
1515 <DL COMPACT>
1516
1517 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
1518 <DD>
1519 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
1520 <DD>
1521 <A NAME="IDX703"></A>
1522 <A NAME="IDX704"></A>
1523 Write output to specified file.
1524
1525 </DL>
1526
1527 <P>
1528 The results are written to standard output if no output file is specified
1529 or if it is <SAMP>`-&acute;</SAMP>.
1530
1531 </P>
1532
1533
1534 <H3><A NAME="SEC106" HREF="gettext_toc.html#TOC106">7.6.3  Message selection</A></H3>
1535
1536 <DL COMPACT>
1537
1538 <DT><SAMP>`-&#60; <VAR>number</VAR>&acute;</SAMP>
1539 <DD>
1540 <DT><SAMP>`--less-than=<VAR>number</VAR>&acute;</SAMP>
1541 <DD>
1542 <A NAME="IDX705"></A>
1543 <A NAME="IDX706"></A>
1544 Print messages with less than <VAR>number</VAR> definitions, defaults to infinite
1545 if not set.
1546
1547 <DT><SAMP>`-&#62; <VAR>number</VAR>&acute;</SAMP>
1548 <DD>
1549 <DT><SAMP>`--more-than=<VAR>number</VAR>&acute;</SAMP>
1550 <DD>
1551 <A NAME="IDX707"></A>
1552 <A NAME="IDX708"></A>
1553 Print messages with more than <VAR>number</VAR> definitions, defaults to 1 if not
1554 set.
1555
1556 <DT><SAMP>`-u&acute;</SAMP>
1557 <DD>
1558 <DT><SAMP>`--unique&acute;</SAMP>
1559 <DD>
1560 <A NAME="IDX709"></A>
1561 <A NAME="IDX710"></A>
1562 Shorthand for <SAMP>`--less-than=2&acute;</SAMP>.  Requests that only unique messages be
1563 printed.
1564
1565 </DL>
1566
1567
1568
1569 <H3><A NAME="SEC107" HREF="gettext_toc.html#TOC107">7.6.4  Input file syntax</A></H3>
1570
1571 <DL COMPACT>
1572
1573 <DT><SAMP>`-P&acute;</SAMP>
1574 <DD>
1575 <DT><SAMP>`--properties-input&acute;</SAMP>
1576 <DD>
1577 <A NAME="IDX711"></A>
1578 <A NAME="IDX712"></A>
1579 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
1580 syntax, not in PO file syntax.
1581
1582 <DT><SAMP>`--stringtable-input&acute;</SAMP>
1583 <DD>
1584 <A NAME="IDX713"></A>
1585 Assume the input files are NeXTstep/GNUstep localized resource files in
1586 <CODE>.strings</CODE> syntax, not in PO file syntax.
1587
1588 </DL>
1589
1590
1591
1592 <H3><A NAME="SEC108" HREF="gettext_toc.html#TOC108">7.6.5  Output details</A></H3>
1593
1594 <DL COMPACT>
1595
1596 <DT><SAMP>`--force-po&acute;</SAMP>
1597 <DD>
1598 <A NAME="IDX714"></A>
1599 Always write an output file even if it contains no message.
1600
1601 <DT><SAMP>`-i&acute;</SAMP>
1602 <DD>
1603 <DT><SAMP>`--indent&acute;</SAMP>
1604 <DD>
1605 <A NAME="IDX715"></A>
1606 <A NAME="IDX716"></A>
1607 Write the .po file using indented style.
1608
1609 <DT><SAMP>`--no-location&acute;</SAMP>
1610 <DD>
1611 <A NAME="IDX717"></A>
1612 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
1613
1614 <DT><SAMP>`-n&acute;</SAMP>
1615 <DD>
1616 <DT><SAMP>`--add-location&acute;</SAMP>
1617 <DD>
1618 <A NAME="IDX718"></A>
1619 <A NAME="IDX719"></A>
1620 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
1621
1622 <DT><SAMP>`--strict&acute;</SAMP>
1623 <DD>
1624 <A NAME="IDX720"></A>
1625 Write out a strict Uniforum conforming PO file.  Note that this
1626 Uniforum format should be avoided because it doesn't support the
1627 GNU extensions.
1628
1629 <DT><SAMP>`-p&acute;</SAMP>
1630 <DD>
1631 <DT><SAMP>`--properties-output&acute;</SAMP>
1632 <DD>
1633 <A NAME="IDX721"></A>
1634 <A NAME="IDX722"></A>
1635 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
1636 that this file format doesn't support plural forms and silently drops
1637 obsolete messages.
1638
1639 <DT><SAMP>`--stringtable-output&acute;</SAMP>
1640 <DD>
1641 <A NAME="IDX723"></A>
1642 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
1643 Note that this file format doesn't support plural forms.
1644
1645 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
1646 <DD>
1647 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
1648 <DD>
1649 <A NAME="IDX724"></A>
1650 <A NAME="IDX725"></A>
1651 Set the output page width.  Long strings in the output files will be
1652 split across multiple lines in order to ensure that each line's width
1653 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
1654
1655 <DT><SAMP>`--no-wrap&acute;</SAMP>
1656 <DD>
1657 <A NAME="IDX726"></A>
1658 Do not break long message lines.  Message lines whose width exceeds the
1659 output page width will not be split into several lines.  Only file reference
1660 lines which are wider than the output page width will be split.
1661
1662 <DT><SAMP>`-s&acute;</SAMP>
1663 <DD>
1664 <DT><SAMP>`--sort-output&acute;</SAMP>
1665 <DD>
1666 <A NAME="IDX727"></A>
1667 <A NAME="IDX728"></A>
1668 Generate sorted output.  Note that using this option makes it much harder
1669 for the translator to understand each message's context.
1670
1671 <DT><SAMP>`-F&acute;</SAMP>
1672 <DD>
1673 <DT><SAMP>`--sort-by-file&acute;</SAMP>
1674 <DD>
1675 <A NAME="IDX729"></A>
1676 <A NAME="IDX730"></A>
1677 Sort output by file location.
1678
1679 <DT><SAMP>`--omit-header&acute;</SAMP>
1680 <DD>
1681 <A NAME="IDX731"></A>
1682 Don't write header with <SAMP>`msgid ""&acute;</SAMP> entry.
1683
1684 </DL>
1685
1686
1687
1688 <H3><A NAME="SEC109" HREF="gettext_toc.html#TOC109">7.6.6  Informative output</A></H3>
1689
1690 <DL COMPACT>
1691
1692 <DT><SAMP>`-h&acute;</SAMP>
1693 <DD>
1694 <DT><SAMP>`--help&acute;</SAMP>
1695 <DD>
1696 <A NAME="IDX732"></A>
1697 <A NAME="IDX733"></A>
1698 Display this help and exit.
1699
1700 <DT><SAMP>`-V&acute;</SAMP>
1701 <DD>
1702 <DT><SAMP>`--version&acute;</SAMP>
1703 <DD>
1704 <A NAME="IDX734"></A>
1705 <A NAME="IDX735"></A>
1706 Output version information and exit.
1707
1708 </DL>
1709
1710
1711
1712 <H2><A NAME="SEC110" HREF="gettext_toc.html#TOC110">7.7  Invoking the <CODE>msgcmp</CODE> Program</A></H2>
1713
1714 <P>
1715 <A NAME="IDX736"></A>
1716 <A NAME="IDX737"></A>
1717
1718 <PRE>
1719 msgcmp [<VAR>option</VAR>] <VAR>def</VAR>.po <VAR>ref</VAR>.pot
1720 </PRE>
1721
1722 <P>
1723 <A NAME="IDX738"></A>
1724 The <CODE>msgcmp</CODE> program compares two Uniforum style .po files to check that
1725 both contain the same set of msgid strings.  The <VAR>def</VAR>.po file is an
1726 existing PO file with the translations.  The <VAR>ref</VAR>.pot file is the last
1727 created PO file, or a PO Template file (generally created by <CODE>xgettext</CODE>).
1728 This is useful for checking that you have translated each and every message
1729 in your program.  Where an exact match cannot be found, fuzzy matching is
1730 used to produce better diagnostics.
1731
1732 </P>
1733
1734
1735 <H3><A NAME="SEC111" HREF="gettext_toc.html#TOC111">7.7.1  Input file location</A></H3>
1736
1737 <DL COMPACT>
1738
1739 <DT><SAMP>`<VAR>def</VAR>.po&acute;</SAMP>
1740 <DD>
1741 Translations.
1742
1743 <DT><SAMP>`<VAR>ref</VAR>.pot&acute;</SAMP>
1744 <DD>
1745 References to the sources.
1746
1747 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
1748 <DD>
1749 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
1750 <DD>
1751 <A NAME="IDX739"></A>
1752 <A NAME="IDX740"></A>
1753 Add <VAR>directory</VAR> to the list of directories.  Source files are
1754 searched relative to this list of directories.
1755
1756 </DL>
1757
1758
1759
1760 <H3><A NAME="SEC112" HREF="gettext_toc.html#TOC112">7.7.2  Operation modifiers</A></H3>
1761
1762 <DL COMPACT>
1763
1764 <DT><SAMP>`-m&acute;</SAMP>
1765 <DD>
1766 <DT><SAMP>`--multi-domain&acute;</SAMP>
1767 <DD>
1768 <A NAME="IDX741"></A>
1769 <A NAME="IDX742"></A>
1770 Apply <VAR>ref</VAR>.pot to each of the domains in <VAR>def</VAR>.po.
1771
1772 </DL>
1773
1774
1775
1776 <H3><A NAME="SEC113" HREF="gettext_toc.html#TOC113">7.7.3  Input file syntax</A></H3>
1777
1778 <DL COMPACT>
1779
1780 <DT><SAMP>`-P&acute;</SAMP>
1781 <DD>
1782 <DT><SAMP>`--properties-input&acute;</SAMP>
1783 <DD>
1784 <A NAME="IDX743"></A>
1785 <A NAME="IDX744"></A>
1786 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
1787 syntax, not in PO file syntax.
1788
1789 <DT><SAMP>`--stringtable-input&acute;</SAMP>
1790 <DD>
1791 <A NAME="IDX745"></A>
1792 Assume the input files are NeXTstep/GNUstep localized resource files in
1793 <CODE>.strings</CODE> syntax, not in PO file syntax.
1794
1795 </DL>
1796
1797
1798
1799 <H3><A NAME="SEC114" HREF="gettext_toc.html#TOC114">7.7.4  Informative output</A></H3>
1800
1801 <DL COMPACT>
1802
1803 <DT><SAMP>`-h&acute;</SAMP>
1804 <DD>
1805 <DT><SAMP>`--help&acute;</SAMP>
1806 <DD>
1807 <A NAME="IDX746"></A>
1808 <A NAME="IDX747"></A>
1809 Display this help and exit.
1810
1811 <DT><SAMP>`-V&acute;</SAMP>
1812 <DD>
1813 <DT><SAMP>`--version&acute;</SAMP>
1814 <DD>
1815 <A NAME="IDX748"></A>
1816 <A NAME="IDX749"></A>
1817 Output version information and exit.
1818
1819 </DL>
1820
1821
1822
1823 <H2><A NAME="SEC115" HREF="gettext_toc.html#TOC115">7.8  Invoking the <CODE>msgattrib</CODE> Program</A></H2>
1824
1825 <P>
1826 <A NAME="IDX750"></A>
1827 <A NAME="IDX751"></A>
1828
1829 <PRE>
1830 msgattrib [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
1831 </PRE>
1832
1833 <P>
1834 <A NAME="IDX752"></A>
1835 <A NAME="IDX753"></A>
1836 The <CODE>msgattrib</CODE> program filters the messages of a translation catalog
1837 according to their attributes, and manipulates the attributes.
1838
1839 </P>
1840
1841
1842 <H3><A NAME="SEC116" HREF="gettext_toc.html#TOC116">7.8.1  Input file location</A></H3>
1843
1844 <DL COMPACT>
1845
1846 <DT><SAMP>`<VAR>inputfile</VAR>&acute;</SAMP>
1847 <DD>
1848 Input PO file.
1849
1850 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
1851 <DD>
1852 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
1853 <DD>
1854 <A NAME="IDX754"></A>
1855 <A NAME="IDX755"></A>
1856 Add <VAR>directory</VAR> to the list of directories.  Source files are
1857 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
1858 file will be written relative to the current directory, though.
1859
1860 </DL>
1861
1862 <P>
1863 If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-&acute;</SAMP>, standard input is read.
1864
1865 </P>
1866
1867
1868 <H3><A NAME="SEC117" HREF="gettext_toc.html#TOC117">7.8.2  Output file location</A></H3>
1869
1870 <DL COMPACT>
1871
1872 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
1873 <DD>
1874 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
1875 <DD>
1876 <A NAME="IDX756"></A>
1877 <A NAME="IDX757"></A>
1878 Write output to specified file.
1879
1880 </DL>
1881
1882 <P>
1883 The results are written to standard output if no output file is specified
1884 or if it is <SAMP>`-&acute;</SAMP>.
1885
1886 </P>
1887
1888
1889 <H3><A NAME="SEC118" HREF="gettext_toc.html#TOC118">7.8.3  Message selection</A></H3>
1890
1891 <DL COMPACT>
1892
1893 <DT><SAMP>`--translated&acute;</SAMP>
1894 <DD>
1895 <A NAME="IDX758"></A>
1896 Keep translated messages, remove untranslated messages.
1897
1898 <DT><SAMP>`--untranslated&acute;</SAMP>
1899 <DD>
1900 <A NAME="IDX759"></A>
1901 Keep untranslated messages, remove translated messages.
1902
1903 <DT><SAMP>`--no-fuzzy&acute;</SAMP>
1904 <DD>
1905 <A NAME="IDX760"></A>
1906 Remove `fuzzy' marked messages.
1907
1908 <DT><SAMP>`--only-fuzzy&acute;</SAMP>
1909 <DD>
1910 <A NAME="IDX761"></A>
1911 Keep `fuzzy' marked messages, remove all other messsages.
1912
1913 <DT><SAMP>`--no-obsolete&acute;</SAMP>
1914 <DD>
1915 <A NAME="IDX762"></A>
1916 Remove obsolete #~ messages.
1917
1918 <DT><SAMP>`--only-obsolete&acute;</SAMP>
1919 <DD>
1920 <A NAME="IDX763"></A>
1921 Keep obsolete #~ messages, remove all other messages.
1922
1923 </DL>
1924
1925
1926
1927 <H3><A NAME="SEC119" HREF="gettext_toc.html#TOC119">7.8.4  Attribute manipulation</A></H3>
1928
1929 <P>
1930 <A NAME="IDX764"></A>
1931 Attributes are modified after the message selection/removal has been
1932 performed.  If the <SAMP>`--only-file&acute;</SAMP> or <SAMP>`--ignore-file&acute;</SAMP> option is
1933 specified, the attribute modification is applied only to those messages
1934 that are listed in the <VAR>only-file</VAR> and not listed in the
1935 <VAR>ignore-file</VAR>.
1936
1937 </P>
1938 <DL COMPACT>
1939
1940 <DT><SAMP>`--set-fuzzy&acute;</SAMP>
1941 <DD>
1942 <A NAME="IDX765"></A>
1943 Set all messages `fuzzy'.
1944
1945 <DT><SAMP>`--clear-fuzzy&acute;</SAMP>
1946 <DD>
1947 <A NAME="IDX766"></A>
1948 Set all messages non-`fuzzy'.
1949
1950 <DT><SAMP>`--set-obsolete&acute;</SAMP>
1951 <DD>
1952 <A NAME="IDX767"></A>
1953 Set all messages obsolete.
1954
1955 <DT><SAMP>`--clear-obsolete&acute;</SAMP>
1956 <DD>
1957 <A NAME="IDX768"></A>
1958 Set all messages non-obsolete.
1959
1960 <DT><SAMP>`--only-file=<VAR>file</VAR>&acute;</SAMP>
1961 <DD>
1962 <A NAME="IDX769"></A>
1963 Limit the attribute changes to entries that are listed in <VAR>file</VAR>.
1964 <VAR>file</VAR> should be a PO or POT file.
1965
1966 <DT><SAMP>`--ignore-file=<VAR>file</VAR>&acute;</SAMP>
1967 <DD>
1968 <A NAME="IDX770"></A>
1969 Limit the attribute changes to entries that are not listed in <VAR>file</VAR>.
1970 <VAR>file</VAR> should be a PO or POT file.
1971
1972 <DT><SAMP>`--fuzzy&acute;</SAMP>
1973 <DD>
1974 <A NAME="IDX771"></A>
1975 Synonym for <SAMP>`--only-fuzzy --clear-fuzzy&acute;</SAMP>: It keeps only the fuzzy
1976 messages and removes their `fuzzy' mark.
1977
1978 <DT><SAMP>`--obsolete&acute;</SAMP>
1979 <DD>
1980 <A NAME="IDX772"></A>
1981 Synonym for <SAMP>`--only-obsolete --clear-obsolete&acute;</SAMP>: It keeps only the
1982 obsolete messages and makes them non-obsolete.
1983
1984 </DL>
1985
1986
1987
1988 <H3><A NAME="SEC120" HREF="gettext_toc.html#TOC120">7.8.5  Input file syntax</A></H3>
1989
1990 <DL COMPACT>
1991
1992 <DT><SAMP>`-P&acute;</SAMP>
1993 <DD>
1994 <DT><SAMP>`--properties-input&acute;</SAMP>
1995 <DD>
1996 <A NAME="IDX773"></A>
1997 <A NAME="IDX774"></A>
1998 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
1999 syntax, not in PO file syntax.
2000
2001 <DT><SAMP>`--stringtable-input&acute;</SAMP>
2002 <DD>
2003 <A NAME="IDX775"></A>
2004 Assume the input file is a NeXTstep/GNUstep localized resource file in
2005 <CODE>.strings</CODE> syntax, not in PO file syntax.
2006
2007 </DL>
2008
2009
2010
2011 <H3><A NAME="SEC121" HREF="gettext_toc.html#TOC121">7.8.6  Output details</A></H3>
2012
2013 <DL COMPACT>
2014
2015 <DT><SAMP>`--force-po&acute;</SAMP>
2016 <DD>
2017 <A NAME="IDX776"></A>
2018 Always write an output file even if it contains no message.
2019
2020 <DT><SAMP>`-i&acute;</SAMP>
2021 <DD>
2022 <DT><SAMP>`--indent&acute;</SAMP>
2023 <DD>
2024 <A NAME="IDX777"></A>
2025 <A NAME="IDX778"></A>
2026 Write the .po file using indented style.
2027
2028 <DT><SAMP>`--no-location&acute;</SAMP>
2029 <DD>
2030 <A NAME="IDX779"></A>
2031 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
2032
2033 <DT><SAMP>`-n&acute;</SAMP>
2034 <DD>
2035 <DT><SAMP>`--add-location&acute;</SAMP>
2036 <DD>
2037 <A NAME="IDX780"></A>
2038 <A NAME="IDX781"></A>
2039 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
2040
2041 <DT><SAMP>`--strict&acute;</SAMP>
2042 <DD>
2043 <A NAME="IDX782"></A>
2044 Write out a strict Uniforum conforming PO file.  Note that this
2045 Uniforum format should be avoided because it doesn't support the
2046 GNU extensions.
2047
2048 <DT><SAMP>`-p&acute;</SAMP>
2049 <DD>
2050 <DT><SAMP>`--properties-output&acute;</SAMP>
2051 <DD>
2052 <A NAME="IDX783"></A>
2053 <A NAME="IDX784"></A>
2054 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
2055 that this file format doesn't support plural forms and silently drops
2056 obsolete messages.
2057
2058 <DT><SAMP>`--stringtable-output&acute;</SAMP>
2059 <DD>
2060 <A NAME="IDX785"></A>
2061 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
2062 Note that this file format doesn't support plural forms.
2063
2064 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
2065 <DD>
2066 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
2067 <DD>
2068 <A NAME="IDX786"></A>
2069 <A NAME="IDX787"></A>
2070 Set the output page width.  Long strings in the output files will be
2071 split across multiple lines in order to ensure that each line's width
2072 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
2073
2074 <DT><SAMP>`--no-wrap&acute;</SAMP>
2075 <DD>
2076 <A NAME="IDX788"></A>
2077 Do not break long message lines.  Message lines whose width exceeds the
2078 output page width will not be split into several lines.  Only file reference
2079 lines which are wider than the output page width will be split.
2080
2081 <DT><SAMP>`-s&acute;</SAMP>
2082 <DD>
2083 <DT><SAMP>`--sort-output&acute;</SAMP>
2084 <DD>
2085 <A NAME="IDX789"></A>
2086 <A NAME="IDX790"></A>
2087 Generate sorted output.  Note that using this option makes it much harder
2088 for the translator to understand each message's context.
2089
2090 <DT><SAMP>`-F&acute;</SAMP>
2091 <DD>
2092 <DT><SAMP>`--sort-by-file&acute;</SAMP>
2093 <DD>
2094 <A NAME="IDX791"></A>
2095 <A NAME="IDX792"></A>
2096 Sort output by file location.
2097
2098 </DL>
2099
2100
2101
2102 <H3><A NAME="SEC122" HREF="gettext_toc.html#TOC122">7.8.7  Informative output</A></H3>
2103
2104 <DL COMPACT>
2105
2106 <DT><SAMP>`-h&acute;</SAMP>
2107 <DD>
2108 <DT><SAMP>`--help&acute;</SAMP>
2109 <DD>
2110 <A NAME="IDX793"></A>
2111 <A NAME="IDX794"></A>
2112 Display this help and exit.
2113
2114 <DT><SAMP>`-V&acute;</SAMP>
2115 <DD>
2116 <DT><SAMP>`--version&acute;</SAMP>
2117 <DD>
2118 <A NAME="IDX795"></A>
2119 <A NAME="IDX796"></A>
2120 Output version information and exit.
2121
2122 </DL>
2123
2124
2125
2126 <H2><A NAME="SEC123" HREF="gettext_toc.html#TOC123">7.9  Invoking the <CODE>msgen</CODE> Program</A></H2>
2127
2128 <P>
2129 <A NAME="IDX797"></A>
2130 <A NAME="IDX798"></A>
2131
2132 <PRE>
2133 msgen [<VAR>option</VAR>] <VAR>inputfile</VAR>
2134 </PRE>
2135
2136 <P>
2137 <A NAME="IDX799"></A>
2138 The <CODE>msgen</CODE> program creates an English translation catalog.  The
2139 input file is the last created English PO file, or a PO Template file
2140 (generally created by xgettext).  Untranslated entries are assigned a
2141 translation that is identical to the msgid.
2142
2143 </P>
2144 <P>
2145 Note: <SAMP>`msginit --no-translator --locale=en&acute;</SAMP> performs a very similar
2146 task.  The main difference is that <CODE>msginit</CODE> cares specially about
2147 the header entry, whereas <CODE>msgen</CODE> doesn't.
2148
2149 </P>
2150
2151
2152 <H3><A NAME="SEC124" HREF="gettext_toc.html#TOC124">7.9.1  Input file location</A></H3>
2153
2154 <DL COMPACT>
2155
2156 <DT><SAMP>`<VAR>inputfile</VAR>&acute;</SAMP>
2157 <DD>
2158 Input PO or POT file.
2159
2160 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
2161 <DD>
2162 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
2163 <DD>
2164 <A NAME="IDX800"></A>
2165 <A NAME="IDX801"></A>
2166 Add <VAR>directory</VAR> to the list of directories.  Source files are
2167 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
2168 file will be written relative to the current directory, though.
2169
2170 </DL>
2171
2172 <P>
2173 If <VAR>inputfile</VAR> is <SAMP>`-&acute;</SAMP>, standard input is read.
2174
2175 </P>
2176
2177
2178 <H3><A NAME="SEC125" HREF="gettext_toc.html#TOC125">7.9.2  Output file location</A></H3>
2179
2180 <DL COMPACT>
2181
2182 <DT><SAMP>`-o <VAR>file</VAR>&acute;</SAMP>
2183 <DD>
2184 <DT><SAMP>`--output-file=<VAR>file</VAR>&acute;</SAMP>
2185 <DD>
2186 <A NAME="IDX802"></A>
2187 <A NAME="IDX803"></A>
2188 Write output to specified file.
2189
2190 </DL>
2191
2192 <P>
2193 The results are written to standard output if no output file is specified
2194 or if it is <SAMP>`-&acute;</SAMP>.
2195
2196 </P>
2197
2198
2199 <H3><A NAME="SEC126" HREF="gettext_toc.html#TOC126">7.9.3  Input file syntax</A></H3>
2200
2201 <DL COMPACT>
2202
2203 <DT><SAMP>`-P&acute;</SAMP>
2204 <DD>
2205 <DT><SAMP>`--properties-input&acute;</SAMP>
2206 <DD>
2207 <A NAME="IDX804"></A>
2208 <A NAME="IDX805"></A>
2209 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
2210 syntax, not in PO file syntax.
2211
2212 <DT><SAMP>`--stringtable-input&acute;</SAMP>
2213 <DD>
2214 <A NAME="IDX806"></A>
2215 Assume the input file is a NeXTstep/GNUstep localized resource file in
2216 <CODE>.strings</CODE> syntax, not in PO file syntax.
2217
2218 </DL>
2219
2220
2221
2222 <H3><A NAME="SEC127" HREF="gettext_toc.html#TOC127">7.9.4  Output details</A></H3>
2223
2224 <DL COMPACT>
2225
2226 <DT><SAMP>`--force-po&acute;</SAMP>
2227 <DD>
2228 <A NAME="IDX807"></A>
2229 Always write an output file even if it contains no message.
2230
2231 <DT><SAMP>`-i&acute;</SAMP>
2232 <DD>
2233 <DT><SAMP>`--indent&acute;</SAMP>
2234 <DD>
2235 <A NAME="IDX808"></A>
2236 <A NAME="IDX809"></A>
2237 Write the .po file using indented style.
2238
2239 <DT><SAMP>`--no-location&acute;</SAMP>
2240 <DD>
2241 <A NAME="IDX810"></A>
2242 Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines.
2243
2244 <DT><SAMP>`--add-location&acute;</SAMP>
2245 <DD>
2246 <A NAME="IDX811"></A>
2247 Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>&acute;</SAMP> lines (default).
2248
2249 <DT><SAMP>`--strict&acute;</SAMP>
2250 <DD>
2251 <A NAME="IDX812"></A>
2252 Write out a strict Uniforum conforming PO file.  Note that this
2253 Uniforum format should be avoided because it doesn't support the
2254 GNU extensions.
2255
2256 <DT><SAMP>`-p&acute;</SAMP>
2257 <DD>
2258 <DT><SAMP>`--properties-output&acute;</SAMP>
2259 <DD>
2260 <A NAME="IDX813"></A>
2261 <A NAME="IDX814"></A>
2262 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax.  Note
2263 that this file format doesn't support plural forms and silently drops
2264 obsolete messages.
2265
2266 <DT><SAMP>`--stringtable-output&acute;</SAMP>
2267 <DD>
2268 <A NAME="IDX815"></A>
2269 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
2270 Note that this file format doesn't support plural forms.
2271
2272 <DT><SAMP>`-w <VAR>number</VAR>&acute;</SAMP>
2273 <DD>
2274 <DT><SAMP>`--width=<VAR>number</VAR>&acute;</SAMP>
2275 <DD>
2276 <A NAME="IDX816"></A>
2277 <A NAME="IDX817"></A>
2278 Set the output page width.  Long strings in the output files will be
2279 split across multiple lines in order to ensure that each line's width
2280 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
2281
2282 <DT><SAMP>`--no-wrap&acute;</SAMP>
2283 <DD>
2284 <A NAME="IDX818"></A>
2285 Do not break long message lines.  Message lines whose width exceeds the
2286 output page width will not be split into several lines.  Only file reference
2287 lines which are wider than the output page width will be split.
2288
2289 <DT><SAMP>`-s&acute;</SAMP>
2290 <DD>
2291 <DT><SAMP>`--sort-output&acute;</SAMP>
2292 <DD>
2293 <A NAME="IDX819"></A>
2294 <A NAME="IDX820"></A>
2295 Generate sorted output.  Note that using this option makes it much harder
2296 for the translator to understand each message's context.
2297
2298 <DT><SAMP>`-F&acute;</SAMP>
2299 <DD>
2300 <DT><SAMP>`--sort-by-file&acute;</SAMP>
2301 <DD>
2302 <A NAME="IDX821"></A>
2303 <A NAME="IDX822"></A>
2304 Sort output by file location.
2305
2306 </DL>
2307
2308
2309
2310 <H3><A NAME="SEC128" HREF="gettext_toc.html#TOC128">7.9.5  Informative output</A></H3>
2311
2312 <DL COMPACT>
2313
2314 <DT><SAMP>`-h&acute;</SAMP>
2315 <DD>
2316 <DT><SAMP>`--help&acute;</SAMP>
2317 <DD>
2318 <A NAME="IDX823"></A>
2319 <A NAME="IDX824"></A>
2320 Display this help and exit.
2321
2322 <DT><SAMP>`-V&acute;</SAMP>
2323 <DD>
2324 <DT><SAMP>`--version&acute;</SAMP>
2325 <DD>
2326 <A NAME="IDX825"></A>
2327 <A NAME="IDX826"></A>
2328 Output version information and exit.
2329
2330 </DL>
2331
2332
2333
2334 <H2><A NAME="SEC129" HREF="gettext_toc.html#TOC129">7.10  Invoking the <CODE>msgexec</CODE> Program</A></H2>
2335
2336 <P>
2337 <A NAME="IDX827"></A>
2338 <A NAME="IDX828"></A>
2339
2340 <PRE>
2341 msgexec [<VAR>option</VAR>] <VAR>command</VAR> [<VAR>command-option</VAR>]
2342 </PRE>
2343
2344 <P>
2345 <A NAME="IDX829"></A>
2346 The <CODE>msgexec</CODE> program applies a command to all translations of a
2347 translation catalog.
2348 The <VAR>command</VAR> can be any program that reads a translation from standard
2349 input.  It is invoked once for each translation.  Its output becomes
2350 msgexec's output.  <CODE>msgexec</CODE>'s return code is the maximum return code
2351 across all invocations.
2352
2353 </P>
2354 <P>
2355 <A NAME="IDX830"></A>
2356 A special builtin command called <SAMP>`0&acute;</SAMP> outputs the translation, followed
2357 by a null byte.  The output of <SAMP>`msgexec 0&acute;</SAMP> is suitable as input for
2358 <SAMP>`xargs -0&acute;</SAMP>.
2359
2360 </P>
2361 <P>
2362 <A NAME="IDX831"></A>
2363 <A NAME="IDX832"></A>
2364 During each <VAR>command</VAR> invocation, the environment variable
2365 <CODE>MSGEXEC_MSGID</CODE> is bound to the message's msgid, and the environment
2366 variable <CODE>MSGEXEC_LOCATION</CODE> is bound to the location in the PO file
2367 of the message.
2368
2369 </P>
2370 <P>
2371 <A NAME="IDX833"></A>
2372 Note: It is your responsibility to ensure that the <VAR>command</VAR> can cope
2373 with input encoded in the translation catalog's encoding.  If the
2374 <VAR>command</VAR> wants input in a particular encoding, you can in a first step
2375 convert the translation catalog to that encoding using the <SAMP>`msgconv&acute;</SAMP>
2376 program, before invoking <SAMP>`msgexec&acute;</SAMP>.  If the <VAR>command</VAR> wants input
2377 in the locale's encoding, but you want to avoid the locale's encoding, then
2378 you can first convert the translation catalog to UTF-8 using the
2379 <SAMP>`msgconv&acute;</SAMP> program and then make <SAMP>`msgexec&acute;</SAMP> work in an UTF-8
2380 locale, by using the <CODE>LC_ALL</CODE> environment variable.
2381
2382 </P>
2383
2384
2385 <H3><A NAME="SEC130" HREF="gettext_toc.html#TOC130">7.10.1  Input file location</A></H3>
2386
2387 <DL COMPACT>
2388
2389 <DT><SAMP>`-i <VAR>inputfile</VAR>&acute;</SAMP>
2390 <DD>
2391 <DT><SAMP>`--input=<VAR>inputfile</VAR>&acute;</SAMP>
2392 <DD>
2393 <A NAME="IDX834"></A>
2394 <A NAME="IDX835"></A>
2395 Input PO file.
2396
2397 <DT><SAMP>`-D <VAR>directory</VAR>&acute;</SAMP>
2398 <DD>
2399 <DT><SAMP>`--directory=<VAR>directory</VAR>&acute;</SAMP>
2400 <DD>
2401 <A NAME="IDX836"></A>
2402 <A NAME="IDX837"></A>
2403 Add <VAR>directory</VAR> to the list of directories.  Source files are
2404 searched relative to this list of directories.  The resulting <TT>`.po&acute;</TT>
2405 file will be written relative to the current directory, though.
2406
2407 </DL>
2408
2409 <P>
2410 If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-&acute;</SAMP>, standard input is read.
2411
2412 </P>
2413
2414
2415 <H3><A NAME="SEC131" HREF="gettext_toc.html#TOC131">7.10.2  Input file syntax</A></H3>
2416
2417 <DL COMPACT>
2418
2419 <DT><SAMP>`-P&acute;</SAMP>
2420 <DD>
2421 <DT><SAMP>`--properties-input&acute;</SAMP>
2422 <DD>
2423 <A NAME="IDX838"></A>
2424 <A NAME="IDX839"></A>
2425 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
2426 syntax, not in PO file syntax.
2427
2428 <DT><SAMP>`--stringtable-input&acute;</SAMP>
2429 <DD>
2430 <A NAME="IDX840"></A>
2431 Assume the input file is a NeXTstep/GNUstep localized resource file in
2432 <CODE>.strings</CODE> syntax, not in PO file syntax.
2433
2434 </DL>
2435
2436
2437
2438 <H3><A NAME="SEC132" HREF="gettext_toc.html#TOC132">7.10.3  Informative output</A></H3>
2439
2440 <DL COMPACT>
2441
2442 <DT><SAMP>`-h&acute;</SAMP>
2443 <DD>
2444 <DT><SAMP>`--help&acute;</SAMP>
2445 <DD>
2446 <A NAME="IDX841"></A>
2447 <A NAME="IDX842"></A>
2448 Display this help and exit.
2449
2450 <DT><SAMP>`-V&acute;</SAMP>
2451 <DD>
2452 <DT><SAMP>`--version&acute;</SAMP>
2453 <DD>
2454 <A NAME="IDX843"></A>
2455 <A NAME="IDX844"></A>
2456 Output version information and exit.
2457
2458 </DL>
2459
2460
2461
2462 <H2><A NAME="SEC133" HREF="gettext_toc.html#TOC133">7.11  Writing your own programs that process PO files</A></H2>
2463
2464 <P>
2465 For the tasks for which a combination of <SAMP>`msgattrib&acute;</SAMP>, <SAMP>`msgcat&acute;</SAMP> etc.
2466 is not sufficient, a set of C functions is provided in a library, to make it
2467 possible to process PO files in your own programs.  When you use this library,
2468 you don't need to write routines to parse the PO file; instead, you retreive
2469 a pointer in memory to each of messages contained in the PO file.  Functions
2470 for writing PO files are not provided at this time.
2471
2472 </P>
2473 <P>
2474 The functions are declared in the header file <SAMP>`&#60;gettext-po.h&#62;&acute;</SAMP>, and are
2475 defined in a library called <SAMP>`libgettextpo&acute;</SAMP>.
2476
2477 </P>
2478 <P>
2479 <DL>
2480 <DT><U>Data Type:</U> <B>po_file_t</B>
2481 <DD><A NAME="IDX845"></A>
2482 This is a pointer type that refers to the contents of a PO file, after it has
2483 been read into memory.
2484 </DL>
2485
2486 </P>
2487 <P>
2488 <DL>
2489 <DT><U>Data Type:</U> <B>po_message_iterator_t</B>
2490 <DD><A NAME="IDX846"></A>
2491 This is a pointer type that refers to an iterator that produces a sequence of
2492 messages.
2493 </DL>
2494
2495 </P>
2496 <P>
2497 <DL>
2498 <DT><U>Data Type:</U> <B>po_message_t</B>
2499 <DD><A NAME="IDX847"></A>
2500 This is a pointer type that refers to a message of a PO file, including its
2501 translation.
2502 </DL>
2503
2504 </P>
2505 <P>
2506 <DL>
2507 <DT><U>Function:</U> po_file_t <B>po_file_read</B> <I>(const char *<VAR>filename</VAR>)</I>
2508 <DD><A NAME="IDX848"></A>
2509 The <CODE>po_file_read</CODE> function reads a PO file into memory.  The file name
2510 is given as argument.  The return value is a handle to the PO file's contents,
2511 valid until <CODE>po_file_free</CODE> is called on it.  In case of error, the return
2512 value is <CODE>NULL</CODE>, and <CODE>errno</CODE> is set.
2513 </DL>
2514
2515 </P>
2516 <P>
2517 <DL>
2518 <DT><U>Function:</U> void <B>po_file_free</B> <I>(po_file_t <VAR>file</VAR>)</I>
2519 <DD><A NAME="IDX849"></A>
2520 The <CODE>po_file_free</CODE> function frees a PO file's contents from memory,
2521 including all messages that are only implicitly accessible through iterators.
2522 </DL>
2523
2524 </P>
2525 <P>
2526 <DL>
2527 <DT><U>Function:</U> const char * const * <B>po_file_domains</B> <I>(po_file_t <VAR>file</VAR>)</I>
2528 <DD><A NAME="IDX850"></A>
2529 The <CODE>po_file_domains</CODE> function returns the domains for which the given
2530 PO file has messages.  The return value is a <CODE>NULL</CODE> terminated array
2531 which is valid as long as the <VAR>file</VAR> handle is valid.  For PO files which
2532 contain no <SAMP>`domain&acute;</SAMP> directive, the return value contains only one domain,
2533 namely the default domain <CODE>"messages"</CODE>.
2534 </DL>
2535
2536 </P>
2537 <P>
2538 <DL>
2539 <DT><U>Function:</U> po_message_iterator_t <B>po_message_iterator</B> <I>(po_file_t <VAR>file</VAR>, const char *<VAR>domain</VAR>)</I>
2540 <DD><A NAME="IDX851"></A>
2541 The <CODE>po_message_iterator</CODE> returns an iterator that will produce the
2542 messages of <VAR>file</VAR> that belong to the given <VAR>domain</VAR>.  If <VAR>domain</VAR>
2543 is <CODE>NULL</CODE>, the default domain is used instead.  To list the messages,
2544 use the function <CODE>po_next_message</CODE> repeatedly.
2545 </DL>
2546
2547 </P>
2548 <P>
2549 <DL>
2550 <DT><U>Function:</U> void <B>po_message_iterator_free</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I>
2551 <DD><A NAME="IDX852"></A>
2552 The <CODE>po_message_iterator_free</CODE> function frees an iterator previously
2553 allocated through the <CODE>po_message_iterator</CODE> function.
2554 </DL>
2555
2556 </P>
2557 <P>
2558 <DL>
2559 <DT><U>Function:</U> po_message_t <B>po_next_message</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I>
2560 <DD><A NAME="IDX853"></A>
2561 The <CODE>po_next_message</CODE> function returns the next message from
2562 <VAR>iterator</VAR> and advances the iterator.  It returns <CODE>NULL</CODE> when the
2563 iterator has reached the end of its message list.
2564 </DL>
2565
2566 </P>
2567 <P>
2568 The following functions returns details of a <CODE>po_message_t</CODE>.  Recall
2569 that the results are valid as long as the <VAR>file</VAR> handle is valid.
2570
2571 </P>
2572 <P>
2573 <DL>
2574 <DT><U>Function:</U> const char * <B>po_message_msgid</B> <I>(po_message_t <VAR>message</VAR>)</I>
2575 <DD><A NAME="IDX854"></A>
2576 The <CODE>po_message_msgid</CODE> function returns the <CODE>msgid</CODE> (untranslated
2577 English string) of a message.  This is guaranteed to be non-<CODE>NULL</CODE>.
2578 </DL>
2579
2580 </P>
2581 <P>
2582 <DL>
2583 <DT><U>Function:</U> const char * <B>po_message_msgid_plural</B> <I>(po_message_t <VAR>message</VAR>)</I>
2584 <DD><A NAME="IDX855"></A>
2585 The <CODE>po_message_msgid_plural</CODE> function returns the <CODE>msgid_plural</CODE>
2586 (untranslated English plural string) of a message with plurals, or <CODE>NULL</CODE>
2587 for a message without plural.
2588 </DL>
2589
2590 </P>
2591 <P>
2592 <DL>
2593 <DT><U>Function:</U> const char * <B>po_message_msgstr</B> <I>(po_message_t <VAR>message</VAR>)</I>
2594 <DD><A NAME="IDX856"></A>
2595 The <CODE>po_message_msgstr</CODE> function returns the <CODE>msgstr</CODE> (translation)
2596 of a message.  For an untranslated message, the return value is an empty
2597 string.
2598 </DL>
2599
2600 </P>
2601 <P>
2602 <DL>
2603 <DT><U>Function:</U> const char * <B>po_message_msgstr_plural</B> <I>(po_message_t <VAR>message</VAR>, int <VAR>index</VAR>)</I>
2604 <DD><A NAME="IDX857"></A>
2605 The <CODE>po_message_msgstr_plural</CODE> function returns the
2606 <CODE>msgstr[<VAR>index</VAR>]</CODE> of a message with plurals, or <CODE>NULL</CODE> when
2607 the <VAR>index</VAR> is out of range or for a message without plural.
2608 </DL>
2609
2610 </P>
2611 <P>
2612 Here is an example code how these functions can be used.
2613
2614 </P>
2615
2616 <PRE>
2617 const char *filename = ...;
2618 po_file_t file = po_file_read (filename);
2619
2620 if (file == NULL)
2621   error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
2622 {
2623   const char * const *domains = po_file_domains (file);
2624   const char * const *domainp;
2625
2626   for (domainp = domains; *domainp; domainp++)
2627     {
2628       const char *domain = *domainp;
2629       po_message_iterator_t iterator = po_message_iterator (file, domain);
2630
2631       for (;;)
2632         {
2633           po_message_t *message = po_next_message (iterator);
2634
2635           if (message == NULL)
2636             break;
2637           {
2638             const char *msgid = po_message_msgid (message);
2639             const char *msgstr = po_message_msgstr (message);
2640
2641             ...
2642           }
2643         }
2644       po_message_iterator_free (iterator);
2645     }
2646 }
2647 po_file_free (file);
2648 </PRE>
2649
2650 <P><HR><P>
2651 Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_6.html">previous</A>, <A HREF="gettext_8.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>.
2652 </BODY>
2653 </HTML>