1<HTML> 2<HEAD> 3<!-- This HTML file has been created by texi2html 1.52b 4 from gettext.texi on 29 December 2011 --> 5 6<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8"> 7<TITLE>GNU gettext utilities - 9 Manipulating PO Files</TITLE> 8</HEAD> 9<BODY> 10Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_8.html">previous</A>, <A HREF="gettext_10.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="SEC79" HREF="gettext_toc.html#TOC79">9 Manipulating PO Files</A></H1> 15<P> 16<A NAME="IDX522"></A> 17 18</P> 19<P> 20Sometimes it is necessary to manipulate PO files in a way that is better 21performed automatically than by hand. GNU <CODE>gettext</CODE> includes a 22complete set of tools for this purpose. 23 24</P> 25<P> 26<A NAME="IDX523"></A> 27When merging two packages into a single package, the resulting POT file 28will be the concatenation of the two packages' POT files. Thus the 29maintainer must concatenate the two existing package translations into 30a single translation catalog, for each language. This is best performed 31using <SAMP>‘msgcat’</SAMP>. It is then the translators' duty to deal with any 32possible conflicts that arose during the merge. 33 34</P> 35<P> 36<A NAME="IDX524"></A> 37When a translator takes over the translation job from another translator, 38but she uses a different character encoding in her locale, she will 39convert the catalog to her character encoding. This is best done through 40the <SAMP>‘msgconv’</SAMP> program. 41 42</P> 43<P> 44When a maintainer takes a source file with tagged messages from another 45package, he should also take the existing translations for this source 46file (and not let the translators do the same job twice). One way to do 47this is through <SAMP>‘msggrep’</SAMP>, another is to create a POT file for 48that source file and use <SAMP>‘msgmerge’</SAMP>. 49 50</P> 51<P> 52<A NAME="IDX525"></A> 53<A NAME="IDX526"></A> 54When a translator wants to adjust some translation catalog for a special 55dialect or orthography -- for example, German as written in Switzerland 56versus German as written in Germany -- she needs to apply some text 57processing to every message in the catalog. The tool for doing this is 58<SAMP>‘msgfilter’</SAMP>. 59 60</P> 61<P> 62Another use of <CODE>msgfilter</CODE> is to produce approximately the POT file for 63which a given PO file was made. This can be done through a filter command 64like <SAMP>‘msgfilter sed -e d | sed -e '/^# /d'’</SAMP>. Note that the original 65POT file may have had different comments and different plural message counts, 66that's why it's better to use the original POT file if available. 67 68</P> 69<P> 70<A NAME="IDX527"></A> 71When a translator wants to check her translations, for example according 72to orthography rules or using a non-interactive spell checker, she can do 73so using the <SAMP>‘msgexec’</SAMP> program. 74 75</P> 76<P> 77<A NAME="IDX528"></A> 78When third party tools create PO or POT files, sometimes duplicates cannot 79be avoided. But the GNU <CODE>gettext</CODE> tools give an error when they 80encounter duplicate msgids in the same file and in the same domain. 81To merge duplicates, the <SAMP>‘msguniq’</SAMP> program can be used. 82 83</P> 84<P> 85<SAMP>‘msgcomm’</SAMP> is a more general tool for keeping or throwing away 86duplicates, occurring in different files. 87 88</P> 89<P> 90<SAMP>‘msgcmp’</SAMP> can be used to check whether a translation catalog is 91completely translated. 92 93</P> 94<P> 95<A NAME="IDX529"></A> 96<SAMP>‘msgattrib’</SAMP> can be used to select and extract only the fuzzy 97or untranslated messages of a translation catalog. 98 99</P> 100<P> 101<SAMP>‘msgen’</SAMP> is useful as a first step for preparing English translation 102catalogs. It copies each message's msgid to its msgstr. 103 104</P> 105<P> 106Finally, for those applications where all these various programs are not 107sufficient, a library <SAMP>‘libgettextpo’</SAMP> is provided that can be used to 108write other specialized programs that process PO files. 109 110</P> 111 112 113 114<H2><A NAME="SEC80" HREF="gettext_toc.html#TOC80">9.1 Invoking the <CODE>msgcat</CODE> Program</A></H2> 115 116<P> 117<A NAME="IDX530"></A> 118<A NAME="IDX531"></A> 119 120<PRE> 121msgcat [<VAR>option</VAR>] [<VAR>inputfile</VAR>]... 122</PRE> 123 124<P> 125<A NAME="IDX532"></A> 126<A NAME="IDX533"></A> 127The <CODE>msgcat</CODE> program concatenates and merges the specified PO files. 128It finds messages which are common to two or more of the specified PO files. 129By using the <CODE>--more-than</CODE> option, greater commonality may be requested 130before messages are printed. Conversely, the <CODE>--less-than</CODE> option may be 131used to specify less commonality before messages are printed (i.e. 132<SAMP>‘--less-than=2’</SAMP> will only print the unique messages). Translations, 133comments and extract comments will be cumulated, except that if 134<CODE>--use-first</CODE> is specified, they will be taken from the first PO file 135to define them. File positions from all PO files will be cumulated. 136 137</P> 138 139 140<H3><A NAME="SEC81" HREF="gettext_toc.html#TOC81">9.1.1 Input file location</A></H3> 141 142<DL COMPACT> 143 144<DT><SAMP>‘<VAR>inputfile</VAR> ...’</SAMP> 145<DD> 146Input files. 147 148<DT><SAMP>‘-f <VAR>file</VAR>’</SAMP> 149<DD> 150<DT><SAMP>‘--files-from=<VAR>file</VAR>’</SAMP> 151<DD> 152<A NAME="IDX534"></A> 153<A NAME="IDX535"></A> 154Read the names of the input files from <VAR>file</VAR> instead of getting 155them from the command line. 156 157<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 158<DD> 159<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 160<DD> 161<A NAME="IDX536"></A> 162<A NAME="IDX537"></A> 163Add <VAR>directory</VAR> to the list of directories. Source files are 164searched relative to this list of directories. The resulting <TT>‘.po’</TT> 165file will be written relative to the current directory, though. 166 167</DL> 168 169<P> 170If <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read. 171 172</P> 173 174 175<H3><A NAME="SEC82" HREF="gettext_toc.html#TOC82">9.1.2 Output file location</A></H3> 176 177<DL COMPACT> 178 179<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 180<DD> 181<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 182<DD> 183<A NAME="IDX538"></A> 184<A NAME="IDX539"></A> 185Write output to specified file. 186 187</DL> 188 189<P> 190<A NAME="IDX540"></A> 191The results are written to standard output if no output file is specified 192or if it is <SAMP>‘-’</SAMP>. 193 194</P> 195 196 197<H3><A NAME="SEC83" HREF="gettext_toc.html#TOC83">9.1.3 Message selection</A></H3> 198 199<DL COMPACT> 200 201<DT><SAMP>‘-< <VAR>number</VAR>’</SAMP> 202<DD> 203<DT><SAMP>‘--less-than=<VAR>number</VAR>’</SAMP> 204<DD> 205<A NAME="IDX541"></A> 206<A NAME="IDX542"></A> 207Print messages with less than <VAR>number</VAR> definitions, defaults to infinite 208if not set. 209 210<DT><SAMP>‘-> <VAR>number</VAR>’</SAMP> 211<DD> 212<DT><SAMP>‘--more-than=<VAR>number</VAR>’</SAMP> 213<DD> 214<A NAME="IDX543"></A> 215<A NAME="IDX544"></A> 216Print messages with more than <VAR>number</VAR> definitions, defaults to 0 if not 217set. 218 219<DT><SAMP>‘-u’</SAMP> 220<DD> 221<DT><SAMP>‘--unique’</SAMP> 222<DD> 223<A NAME="IDX545"></A> 224<A NAME="IDX546"></A> 225Shorthand for <SAMP>‘--less-than=2’</SAMP>. Requests that only unique messages be 226printed. 227 228</DL> 229 230 231 232<H3><A NAME="SEC84" HREF="gettext_toc.html#TOC84">9.1.4 Input file syntax</A></H3> 233 234<DL COMPACT> 235 236<DT><SAMP>‘-P’</SAMP> 237<DD> 238<DT><SAMP>‘--properties-input’</SAMP> 239<DD> 240<A NAME="IDX547"></A> 241<A NAME="IDX548"></A> 242Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE> 243syntax, not in PO file syntax. 244 245<DT><SAMP>‘--stringtable-input’</SAMP> 246<DD> 247<A NAME="IDX549"></A> 248Assume the input files are NeXTstep/GNUstep localized resource files in 249<CODE>.strings</CODE> syntax, not in PO file syntax. 250 251</DL> 252 253 254 255<H3><A NAME="SEC85" HREF="gettext_toc.html#TOC85">9.1.5 Output details</A></H3> 256 257<DL COMPACT> 258 259<DT><SAMP>‘-t’</SAMP> 260<DD> 261<DT><SAMP>‘--to-code=<VAR>name</VAR>’</SAMP> 262<DD> 263<A NAME="IDX550"></A> 264<A NAME="IDX551"></A> 265Specify encoding for output. 266 267<DT><SAMP>‘--use-first’</SAMP> 268<DD> 269<A NAME="IDX552"></A> 270Use first available translation for each message. Don't merge several 271translations into one. 272 273<DT><SAMP>‘--color’</SAMP> 274<DD> 275<DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP> 276<DD> 277<A NAME="IDX553"></A> 278Specify whether or when to use colors and other text attributes. 279See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details. 280 281<DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP> 282<DD> 283<A NAME="IDX554"></A> 284Specify the CSS style rule file to use for <CODE>--color</CODE>. 285See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details. 286 287<DT><SAMP>‘--force-po’</SAMP> 288<DD> 289<A NAME="IDX555"></A> 290Always write an output file even if it contains no message. 291 292<DT><SAMP>‘-i’</SAMP> 293<DD> 294<DT><SAMP>‘--indent’</SAMP> 295<DD> 296<A NAME="IDX556"></A> 297<A NAME="IDX557"></A> 298Write the .po file using indented style. 299 300<DT><SAMP>‘--no-location’</SAMP> 301<DD> 302<A NAME="IDX558"></A> 303Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 304 305<DT><SAMP>‘-n’</SAMP> 306<DD> 307<DT><SAMP>‘--add-location’</SAMP> 308<DD> 309<A NAME="IDX559"></A> 310<A NAME="IDX560"></A> 311Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 312 313<DT><SAMP>‘--strict’</SAMP> 314<DD> 315<A NAME="IDX561"></A> 316Write out a strict Uniforum conforming PO file. Note that this 317Uniforum format should be avoided because it doesn't support the 318GNU extensions. 319 320<DT><SAMP>‘-p’</SAMP> 321<DD> 322<DT><SAMP>‘--properties-output’</SAMP> 323<DD> 324<A NAME="IDX562"></A> 325<A NAME="IDX563"></A> 326Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 327that this file format doesn't support plural forms and silently drops 328obsolete messages. 329 330<DT><SAMP>‘--stringtable-output’</SAMP> 331<DD> 332<A NAME="IDX564"></A> 333Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 334Note that this file format doesn't support plural forms. 335 336<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 337<DD> 338<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 339<DD> 340<A NAME="IDX565"></A> 341<A NAME="IDX566"></A> 342Set the output page width. Long strings in the output files will be 343split across multiple lines in order to ensure that each line's width 344(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 345 346<DT><SAMP>‘--no-wrap’</SAMP> 347<DD> 348<A NAME="IDX567"></A> 349Do not break long message lines. Message lines whose width exceeds the 350output page width will not be split into several lines. Only file reference 351lines which are wider than the output page width will be split. 352 353<DT><SAMP>‘-s’</SAMP> 354<DD> 355<DT><SAMP>‘--sort-output’</SAMP> 356<DD> 357<A NAME="IDX568"></A> 358<A NAME="IDX569"></A> 359<A NAME="IDX570"></A> 360Generate sorted output. Note that using this option makes it much harder 361for the translator to understand each message's context. 362 363<DT><SAMP>‘-F’</SAMP> 364<DD> 365<DT><SAMP>‘--sort-by-file’</SAMP> 366<DD> 367<A NAME="IDX571"></A> 368<A NAME="IDX572"></A> 369Sort output by file location. 370 371</DL> 372 373 374 375<H3><A NAME="SEC86" HREF="gettext_toc.html#TOC86">9.1.6 Informative output</A></H3> 376 377<DL COMPACT> 378 379<DT><SAMP>‘-h’</SAMP> 380<DD> 381<DT><SAMP>‘--help’</SAMP> 382<DD> 383<A NAME="IDX573"></A> 384<A NAME="IDX574"></A> 385Display this help and exit. 386 387<DT><SAMP>‘-V’</SAMP> 388<DD> 389<DT><SAMP>‘--version’</SAMP> 390<DD> 391<A NAME="IDX575"></A> 392<A NAME="IDX576"></A> 393Output version information and exit. 394 395</DL> 396 397 398 399<H2><A NAME="SEC87" HREF="gettext_toc.html#TOC87">9.2 Invoking the <CODE>msgconv</CODE> Program</A></H2> 400 401<P> 402<A NAME="IDX577"></A> 403<A NAME="IDX578"></A> 404 405<PRE> 406msgconv [<VAR>option</VAR>] [<VAR>inputfile</VAR>] 407</PRE> 408 409<P> 410<A NAME="IDX579"></A> 411The <CODE>msgconv</CODE> program converts a translation catalog to a different 412character encoding. 413 414</P> 415 416 417<H3><A NAME="SEC88" HREF="gettext_toc.html#TOC88">9.2.1 Input file location</A></H3> 418 419<DL COMPACT> 420 421<DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP> 422<DD> 423Input PO file. 424 425<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 426<DD> 427<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 428<DD> 429<A NAME="IDX580"></A> 430<A NAME="IDX581"></A> 431Add <VAR>directory</VAR> to the list of directories. Source files are 432searched relative to this list of directories. The resulting <TT>‘.po’</TT> 433file will be written relative to the current directory, though. 434 435</DL> 436 437<P> 438If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read. 439 440</P> 441 442 443<H3><A NAME="SEC89" HREF="gettext_toc.html#TOC89">9.2.2 Output file location</A></H3> 444 445<DL COMPACT> 446 447<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 448<DD> 449<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 450<DD> 451<A NAME="IDX582"></A> 452<A NAME="IDX583"></A> 453Write output to specified file. 454 455</DL> 456 457<P> 458The results are written to standard output if no output file is specified 459or if it is <SAMP>‘-’</SAMP>. 460 461</P> 462 463 464<H3><A NAME="SEC90" HREF="gettext_toc.html#TOC90">9.2.3 Conversion target</A></H3> 465 466<DL COMPACT> 467 468<DT><SAMP>‘-t’</SAMP> 469<DD> 470<DT><SAMP>‘--to-code=<VAR>name</VAR>’</SAMP> 471<DD> 472<A NAME="IDX584"></A> 473<A NAME="IDX585"></A> 474Specify encoding for output. 475 476</DL> 477 478<P> 479The default encoding is the current locale's encoding. 480 481</P> 482 483 484<H3><A NAME="SEC91" HREF="gettext_toc.html#TOC91">9.2.4 Input file syntax</A></H3> 485 486<DL COMPACT> 487 488<DT><SAMP>‘-P’</SAMP> 489<DD> 490<DT><SAMP>‘--properties-input’</SAMP> 491<DD> 492<A NAME="IDX586"></A> 493<A NAME="IDX587"></A> 494Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> 495syntax, not in PO file syntax. 496 497<DT><SAMP>‘--stringtable-input’</SAMP> 498<DD> 499<A NAME="IDX588"></A> 500Assume the input file is a NeXTstep/GNUstep localized resource file in 501<CODE>.strings</CODE> syntax, not in PO file syntax. 502 503</DL> 504 505 506 507<H3><A NAME="SEC92" HREF="gettext_toc.html#TOC92">9.2.5 Output details</A></H3> 508 509<DL COMPACT> 510 511<DT><SAMP>‘--force-po’</SAMP> 512<DD> 513<A NAME="IDX589"></A> 514Always write an output file even if it contains no message. 515 516<DT><SAMP>‘-i’</SAMP> 517<DD> 518<DT><SAMP>‘--indent’</SAMP> 519<DD> 520<A NAME="IDX590"></A> 521<A NAME="IDX591"></A> 522Write the .po file using indented style. 523 524<DT><SAMP>‘--no-location’</SAMP> 525<DD> 526<A NAME="IDX592"></A> 527Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 528 529<DT><SAMP>‘--add-location’</SAMP> 530<DD> 531<A NAME="IDX593"></A> 532Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 533 534<DT><SAMP>‘--strict’</SAMP> 535<DD> 536<A NAME="IDX594"></A> 537Write out a strict Uniforum conforming PO file. Note that this 538Uniforum format should be avoided because it doesn't support the 539GNU extensions. 540 541<DT><SAMP>‘-p’</SAMP> 542<DD> 543<DT><SAMP>‘--properties-output’</SAMP> 544<DD> 545<A NAME="IDX595"></A> 546<A NAME="IDX596"></A> 547Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 548that this file format doesn't support plural forms and silently drops 549obsolete messages. 550 551<DT><SAMP>‘--stringtable-output’</SAMP> 552<DD> 553<A NAME="IDX597"></A> 554Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 555Note that this file format doesn't support plural forms. 556 557<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 558<DD> 559<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 560<DD> 561<A NAME="IDX598"></A> 562<A NAME="IDX599"></A> 563Set the output page width. Long strings in the output files will be 564split across multiple lines in order to ensure that each line's width 565(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 566 567<DT><SAMP>‘--no-wrap’</SAMP> 568<DD> 569<A NAME="IDX600"></A> 570Do not break long message lines. Message lines whose width exceeds the 571output page width will not be split into several lines. Only file reference 572lines which are wider than the output page width will be split. 573 574<DT><SAMP>‘-s’</SAMP> 575<DD> 576<DT><SAMP>‘--sort-output’</SAMP> 577<DD> 578<A NAME="IDX601"></A> 579<A NAME="IDX602"></A> 580Generate sorted output. Note that using this option makes it much harder 581for the translator to understand each message's context. 582 583<DT><SAMP>‘-F’</SAMP> 584<DD> 585<DT><SAMP>‘--sort-by-file’</SAMP> 586<DD> 587<A NAME="IDX603"></A> 588<A NAME="IDX604"></A> 589Sort output by file location. 590 591</DL> 592 593 594 595<H3><A NAME="SEC93" HREF="gettext_toc.html#TOC93">9.2.6 Informative output</A></H3> 596 597<DL COMPACT> 598 599<DT><SAMP>‘-h’</SAMP> 600<DD> 601<DT><SAMP>‘--help’</SAMP> 602<DD> 603<A NAME="IDX605"></A> 604<A NAME="IDX606"></A> 605Display this help and exit. 606 607<DT><SAMP>‘-V’</SAMP> 608<DD> 609<DT><SAMP>‘--version’</SAMP> 610<DD> 611<A NAME="IDX607"></A> 612<A NAME="IDX608"></A> 613Output version information and exit. 614 615</DL> 616 617 618 619<H2><A NAME="SEC94" HREF="gettext_toc.html#TOC94">9.3 Invoking the <CODE>msggrep</CODE> Program</A></H2> 620 621<P> 622<A NAME="IDX609"></A> 623<A NAME="IDX610"></A> 624 625<PRE> 626msggrep [<VAR>option</VAR>] [<VAR>inputfile</VAR>] 627</PRE> 628 629<P> 630<A NAME="IDX611"></A> 631The <CODE>msggrep</CODE> program extracts all messages of a translation catalog 632that match a given pattern or belong to some given source files. 633 634</P> 635 636 637<H3><A NAME="SEC95" HREF="gettext_toc.html#TOC95">9.3.1 Input file location</A></H3> 638 639<DL COMPACT> 640 641<DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP> 642<DD> 643Input PO file. 644 645<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 646<DD> 647<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 648<DD> 649<A NAME="IDX612"></A> 650<A NAME="IDX613"></A> 651Add <VAR>directory</VAR> to the list of directories. Source files are 652searched relative to this list of directories. The resulting <TT>‘.po’</TT> 653file will be written relative to the current directory, though. 654 655</DL> 656 657<P> 658If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read. 659 660</P> 661 662 663<H3><A NAME="SEC96" HREF="gettext_toc.html#TOC96">9.3.2 Output file location</A></H3> 664 665<DL COMPACT> 666 667<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 668<DD> 669<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 670<DD> 671<A NAME="IDX614"></A> 672<A NAME="IDX615"></A> 673Write output to specified file. 674 675</DL> 676 677<P> 678The results are written to standard output if no output file is specified 679or if it is <SAMP>‘-’</SAMP>. 680 681</P> 682 683 684<H3><A NAME="SEC97" HREF="gettext_toc.html#TOC97">9.3.3 Message selection</A></H3> 685 686 687<PRE> 688 [-N <VAR>sourcefile</VAR>]... [-M <VAR>domainname</VAR>]... 689 [-J <VAR>msgctxt-pattern</VAR>] [-K <VAR>msgid-pattern</VAR>] [-T <VAR>msgstr-pattern</VAR>] 690 [-C <VAR>comment-pattern</VAR>] 691</PRE> 692 693<P> 694A message is selected if 695 696<UL> 697<LI>it comes from one of the specified source files, 698 699<LI>or if it comes from one of the specified domains, 700 701<LI>or if <SAMP>‘-J’</SAMP> is given and its context (msgctxt) matches 702 703 <VAR>msgctxt-pattern</VAR>, 704<LI>or if <SAMP>‘-K’</SAMP> is given and its key (msgid or msgid_plural) matches 705 706 <VAR>msgid-pattern</VAR>, 707<LI>or if <SAMP>‘-T’</SAMP> is given and its translation (msgstr) matches 708 709 <VAR>msgstr-pattern</VAR>, 710<LI>or if <SAMP>‘-C’</SAMP> is given and the translator's comment matches 711 712 <VAR>comment-pattern</VAR>. 713</UL> 714 715<P> 716When more than one selection criterion is specified, the set of selected 717messages is the union of the selected messages of each criterion. 718 719</P> 720<P> 721<VAR>msgctxt-pattern</VAR> or <VAR>msgid-pattern</VAR> or <VAR>msgstr-pattern</VAR> syntax: 722 723<PRE> 724 [-E | -F] [-e <VAR>pattern</VAR> | -f <VAR>file</VAR>]... 725</PRE> 726 727<P> 728<VAR>pattern</VAR>s are basic regular expressions by default, or extended regular 729expressions if -E is given, or fixed strings if -F is given. 730 731</P> 732<DL COMPACT> 733 734<DT><SAMP>‘-N <VAR>sourcefile</VAR>’</SAMP> 735<DD> 736<DT><SAMP>‘--location=<VAR>sourcefile</VAR>’</SAMP> 737<DD> 738<A NAME="IDX616"></A> 739<A NAME="IDX617"></A> 740Select messages extracted from <VAR>sourcefile</VAR>. <VAR>sourcefile</VAR> can be 741either a literal file name or a wildcard pattern. 742 743<DT><SAMP>‘-M <VAR>domainname</VAR>’</SAMP> 744<DD> 745<DT><SAMP>‘--domain=<VAR>domainname</VAR>’</SAMP> 746<DD> 747<A NAME="IDX618"></A> 748<A NAME="IDX619"></A> 749Select messages belonging to domain <VAR>domainname</VAR>. 750 751<DT><SAMP>‘-J’</SAMP> 752<DD> 753<DT><SAMP>‘--msgctxt’</SAMP> 754<DD> 755<A NAME="IDX620"></A> 756<A NAME="IDX621"></A> 757Start of patterns for the msgctxt. 758 759<DT><SAMP>‘-K’</SAMP> 760<DD> 761<DT><SAMP>‘--msgid’</SAMP> 762<DD> 763<A NAME="IDX622"></A> 764<A NAME="IDX623"></A> 765Start of patterns for the msgid. 766 767<DT><SAMP>‘-T’</SAMP> 768<DD> 769<DT><SAMP>‘--msgstr’</SAMP> 770<DD> 771<A NAME="IDX624"></A> 772<A NAME="IDX625"></A> 773Start of patterns for the msgstr. 774 775<DT><SAMP>‘-C’</SAMP> 776<DD> 777<DT><SAMP>‘--comment’</SAMP> 778<DD> 779<A NAME="IDX626"></A> 780<A NAME="IDX627"></A> 781Start of patterns for the translator's comment. 782 783<DT><SAMP>‘-X’</SAMP> 784<DD> 785<DT><SAMP>‘--extracted-comment’</SAMP> 786<DD> 787<A NAME="IDX628"></A> 788<A NAME="IDX629"></A> 789Start of patterns for the extracted comments. 790 791<DT><SAMP>‘-E’</SAMP> 792<DD> 793<DT><SAMP>‘--extended-regexp’</SAMP> 794<DD> 795<A NAME="IDX630"></A> 796<A NAME="IDX631"></A> 797Specify that <VAR>pattern</VAR> is an extended regular expression. 798 799<DT><SAMP>‘-F’</SAMP> 800<DD> 801<DT><SAMP>‘--fixed-strings’</SAMP> 802<DD> 803<A NAME="IDX632"></A> 804<A NAME="IDX633"></A> 805Specify that <VAR>pattern</VAR> is a set of newline-separated strings. 806 807<DT><SAMP>‘-e <VAR>pattern</VAR>’</SAMP> 808<DD> 809<DT><SAMP>‘--regexp=<VAR>pattern</VAR>’</SAMP> 810<DD> 811<A NAME="IDX634"></A> 812<A NAME="IDX635"></A> 813Use <VAR>pattern</VAR> as a regular expression. 814 815<DT><SAMP>‘-f <VAR>file</VAR>’</SAMP> 816<DD> 817<DT><SAMP>‘--file=<VAR>file</VAR>’</SAMP> 818<DD> 819<A NAME="IDX636"></A> 820<A NAME="IDX637"></A> 821Obtain <VAR>pattern</VAR> from <VAR>file</VAR>. 822 823<DT><SAMP>‘-i’</SAMP> 824<DD> 825<DT><SAMP>‘--ignore-case’</SAMP> 826<DD> 827<A NAME="IDX638"></A> 828<A NAME="IDX639"></A> 829Ignore case distinctions. 830 831<DT><SAMP>‘-v’</SAMP> 832<DD> 833<DT><SAMP>‘--invert-match’</SAMP> 834<DD> 835<A NAME="IDX640"></A> 836<A NAME="IDX641"></A> 837Output only the messages that do not match any selection criterion, instead 838of the messages that match a selection criterion. 839 840</DL> 841 842 843 844<H3><A NAME="SEC98" HREF="gettext_toc.html#TOC98">9.3.4 Input file syntax</A></H3> 845 846<DL COMPACT> 847 848<DT><SAMP>‘-P’</SAMP> 849<DD> 850<DT><SAMP>‘--properties-input’</SAMP> 851<DD> 852<A NAME="IDX642"></A> 853<A NAME="IDX643"></A> 854Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> 855syntax, not in PO file syntax. 856 857<DT><SAMP>‘--stringtable-input’</SAMP> 858<DD> 859<A NAME="IDX644"></A> 860Assume the input file is a NeXTstep/GNUstep localized resource file in 861<CODE>.strings</CODE> syntax, not in PO file syntax. 862 863</DL> 864 865 866 867<H3><A NAME="SEC99" HREF="gettext_toc.html#TOC99">9.3.5 Output details</A></H3> 868 869<DL COMPACT> 870 871<DT><SAMP>‘--force-po’</SAMP> 872<DD> 873<A NAME="IDX645"></A> 874Always write an output file even if it contains no message. 875 876<DT><SAMP>‘--indent’</SAMP> 877<DD> 878<A NAME="IDX646"></A> 879Write the .po file using indented style. 880 881<DT><SAMP>‘--no-location’</SAMP> 882<DD> 883<A NAME="IDX647"></A> 884Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 885 886<DT><SAMP>‘--add-location’</SAMP> 887<DD> 888<A NAME="IDX648"></A> 889Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 890 891<DT><SAMP>‘--strict’</SAMP> 892<DD> 893<A NAME="IDX649"></A> 894Write out a strict Uniforum conforming PO file. Note that this 895Uniforum format should be avoided because it doesn't support the 896GNU extensions. 897 898<DT><SAMP>‘-p’</SAMP> 899<DD> 900<DT><SAMP>‘--properties-output’</SAMP> 901<DD> 902<A NAME="IDX650"></A> 903<A NAME="IDX651"></A> 904Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 905that this file format doesn't support plural forms and silently drops 906obsolete messages. 907 908<DT><SAMP>‘--stringtable-output’</SAMP> 909<DD> 910<A NAME="IDX652"></A> 911Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 912Note that this file format doesn't support plural forms. 913 914<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 915<DD> 916<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 917<DD> 918<A NAME="IDX653"></A> 919<A NAME="IDX654"></A> 920Set the output page width. Long strings in the output files will be 921split across multiple lines in order to ensure that each line's width 922(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 923 924<DT><SAMP>‘--no-wrap’</SAMP> 925<DD> 926<A NAME="IDX655"></A> 927Do not break long message lines. Message lines whose width exceeds the 928output page width will not be split into several lines. Only file reference 929lines which are wider than the output page width will be split. 930 931<DT><SAMP>‘--sort-output’</SAMP> 932<DD> 933<A NAME="IDX656"></A> 934Generate sorted output. Note that using this option makes it much harder 935for the translator to understand each message's context. 936 937<DT><SAMP>‘--sort-by-file’</SAMP> 938<DD> 939<A NAME="IDX657"></A> 940Sort output by file location. 941 942</DL> 943 944 945 946<H3><A NAME="SEC100" HREF="gettext_toc.html#TOC100">9.3.6 Informative output</A></H3> 947 948<DL COMPACT> 949 950<DT><SAMP>‘-h’</SAMP> 951<DD> 952<DT><SAMP>‘--help’</SAMP> 953<DD> 954<A NAME="IDX658"></A> 955<A NAME="IDX659"></A> 956Display this help and exit. 957 958<DT><SAMP>‘-V’</SAMP> 959<DD> 960<DT><SAMP>‘--version’</SAMP> 961<DD> 962<A NAME="IDX660"></A> 963<A NAME="IDX661"></A> 964Output version information and exit. 965 966</DL> 967 968 969 970<H3><A NAME="SEC101" HREF="gettext_toc.html#TOC101">9.3.7 Examples</A></H3> 971 972<P> 973To extract the messages that come from the source files 974<CODE>gnulib-lib/error.c</CODE> and <CODE>gnulib-lib/getopt.c</CODE>: 975 976</P> 977 978<PRE> 979msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po 980</PRE> 981 982<P> 983To extract the messages that contain the string ���Please specify��� in the 984original string: 985 986</P> 987 988<PRE> 989msggrep --msgid -F -e 'Please specify' input.po 990</PRE> 991 992<P> 993To extract the messages that have a context specifier of either ���Menu>File��� 994or ���Menu>Edit��� or a submenu of them: 995 996</P> 997 998<PRE> 999msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po 1000</PRE> 1001 1002<P> 1003To extract the messages whose translation contains one of the strings in the 1004file <CODE>wordlist.txt</CODE>: 1005 1006</P> 1007 1008<PRE> 1009msggrep --msgstr -F -f wordlist.txt input.po 1010</PRE> 1011 1012 1013 1014<H2><A NAME="SEC102" HREF="gettext_toc.html#TOC102">9.4 Invoking the <CODE>msgfilter</CODE> Program</A></H2> 1015 1016<P> 1017<A NAME="IDX662"></A> 1018<A NAME="IDX663"></A> 1019 1020<PRE> 1021msgfilter [<VAR>option</VAR>] <VAR>filter</VAR> [<VAR>filter-option</VAR>] 1022</PRE> 1023 1024<P> 1025<A NAME="IDX664"></A> 1026The <CODE>msgfilter</CODE> program applies a filter to all translations of a 1027translation catalog. 1028 1029</P> 1030 1031 1032<H3><A NAME="SEC103" HREF="gettext_toc.html#TOC103">9.4.1 Input file location</A></H3> 1033 1034<DL COMPACT> 1035 1036<DT><SAMP>‘-i <VAR>inputfile</VAR>’</SAMP> 1037<DD> 1038<DT><SAMP>‘--input=<VAR>inputfile</VAR>’</SAMP> 1039<DD> 1040<A NAME="IDX665"></A> 1041<A NAME="IDX666"></A> 1042Input PO file. 1043 1044<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 1045<DD> 1046<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 1047<DD> 1048<A NAME="IDX667"></A> 1049<A NAME="IDX668"></A> 1050Add <VAR>directory</VAR> to the list of directories. Source files are 1051searched relative to this list of directories. The resulting <TT>‘.po’</TT> 1052file will be written relative to the current directory, though. 1053 1054</DL> 1055 1056<P> 1057If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read. 1058 1059</P> 1060 1061 1062<H3><A NAME="SEC104" HREF="gettext_toc.html#TOC104">9.4.2 Output file location</A></H3> 1063 1064<DL COMPACT> 1065 1066<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 1067<DD> 1068<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 1069<DD> 1070<A NAME="IDX669"></A> 1071<A NAME="IDX670"></A> 1072Write output to specified file. 1073 1074</DL> 1075 1076<P> 1077The results are written to standard output if no output file is specified 1078or if it is <SAMP>‘-’</SAMP>. 1079 1080</P> 1081 1082 1083<H3><A NAME="SEC105" HREF="gettext_toc.html#TOC105">9.4.3 The filter</A></H3> 1084 1085<P> 1086The <VAR>filter</VAR> can be any program that reads a translation from standard 1087input and writes a modified translation to standard output. A frequently 1088used filter is <SAMP>‘sed’</SAMP>. A few particular built-in filters are also 1089recognized. 1090 1091</P> 1092<P> 1093<A NAME="IDX671"></A> 1094Note: If the filter is not a built-in filter, you have to care about encodings: 1095It is your responsibility to ensure that the <VAR>filter</VAR> can cope 1096with input encoded in the translation catalog's encoding. If the 1097<VAR>filter</VAR> wants input in a particular encoding, you can in a first step 1098convert the translation catalog to that encoding using the <SAMP>‘msgconv’</SAMP> 1099program, before invoking <SAMP>‘msgfilter’</SAMP>. If the <VAR>filter</VAR> wants input 1100in the locale's encoding, but you want to avoid the locale's encoding, then 1101you can first convert the translation catalog to UTF-8 using the 1102<SAMP>‘msgconv’</SAMP> program and then make <SAMP>‘msgfilter’</SAMP> work in an UTF-8 1103locale, by using the <CODE>LC_ALL</CODE> environment variable. 1104 1105</P> 1106<P> 1107<A NAME="IDX672"></A> 1108Note: Most translations in a translation catalog don't end with a newline 1109character. For this reason, it is important that the <VAR>filter</VAR> 1110recognizes its last input line even if it ends without a newline, and that 1111it doesn't add an undesired trailing newline at the end. The <SAMP>‘sed’</SAMP> 1112program on some platforms is known to ignore the last line of input if it 1113is not terminated with a newline. You can use GNU <CODE>sed</CODE> instead; it 1114does not have this limitation. 1115 1116</P> 1117 1118 1119<H3><A NAME="SEC106" HREF="gettext_toc.html#TOC106">9.4.4 Useful <VAR>filter-option</VAR>s when the <VAR>filter</VAR> is <SAMP>‘sed’</SAMP></A></H3> 1120 1121<DL COMPACT> 1122 1123<DT><SAMP>‘-e <VAR>script</VAR>’</SAMP> 1124<DD> 1125<DT><SAMP>‘--expression=<VAR>script</VAR>’</SAMP> 1126<DD> 1127<A NAME="IDX673"></A> 1128<A NAME="IDX674"></A> 1129Add <VAR>script</VAR> to the commands to be executed. 1130 1131<DT><SAMP>‘-f <VAR>scriptfile</VAR>’</SAMP> 1132<DD> 1133<DT><SAMP>‘--file=<VAR>scriptfile</VAR>’</SAMP> 1134<DD> 1135<A NAME="IDX675"></A> 1136<A NAME="IDX676"></A> 1137Add the contents of <VAR>scriptfile</VAR> to the commands to be executed. 1138 1139<DT><SAMP>‘-n’</SAMP> 1140<DD> 1141<DT><SAMP>‘--quiet’</SAMP> 1142<DD> 1143<DT><SAMP>‘--silent’</SAMP> 1144<DD> 1145<A NAME="IDX677"></A> 1146<A NAME="IDX678"></A> 1147<A NAME="IDX679"></A> 1148Suppress automatic printing of pattern space. 1149 1150</DL> 1151 1152 1153 1154<H3><A NAME="SEC107" HREF="gettext_toc.html#TOC107">9.4.5 Built-in <VAR>filter</VAR>s</A></H3> 1155 1156<P> 1157<A NAME="IDX680"></A> 1158<A NAME="IDX681"></A> 1159The filter <SAMP>‘recode-sr-latin’</SAMP> is recognized as a built-in filter. 1160The command <SAMP>‘recode-sr-latin’</SAMP> converts Serbian text, written in the 1161Cyrillic script, to the Latin script. 1162The command <SAMP>‘msgfilter recode-sr-latin’</SAMP> applies this conversion to the 1163translations of a PO file. Thus, it can be used to convert an <TT>‘sr.po’</TT> 1164file to an <TT>‘sr@latin.po’</TT> file. 1165 1166</P> 1167<P> 1168The use of built-in filters is not sensitive to the current locale's encoding. 1169Moreover, when used with a built-in filter, <SAMP>‘msgfilter’</SAMP> can automatically 1170convert the message catalog to the UTF-8 encoding when needed. 1171 1172</P> 1173 1174 1175<H3><A NAME="SEC108" HREF="gettext_toc.html#TOC108">9.4.6 Input file syntax</A></H3> 1176 1177<DL COMPACT> 1178 1179<DT><SAMP>‘-P’</SAMP> 1180<DD> 1181<DT><SAMP>‘--properties-input’</SAMP> 1182<DD> 1183<A NAME="IDX682"></A> 1184<A NAME="IDX683"></A> 1185Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> 1186syntax, not in PO file syntax. 1187 1188<DT><SAMP>‘--stringtable-input’</SAMP> 1189<DD> 1190<A NAME="IDX684"></A> 1191Assume the input file is a NeXTstep/GNUstep localized resource file in 1192<CODE>.strings</CODE> syntax, not in PO file syntax. 1193 1194</DL> 1195 1196 1197 1198<H3><A NAME="SEC109" HREF="gettext_toc.html#TOC109">9.4.7 Output details</A></H3> 1199 1200<DL COMPACT> 1201 1202<DT><SAMP>‘--force-po’</SAMP> 1203<DD> 1204<A NAME="IDX685"></A> 1205Always write an output file even if it contains no message. 1206 1207<DT><SAMP>‘--indent’</SAMP> 1208<DD> 1209<A NAME="IDX686"></A> 1210Write the .po file using indented style. 1211 1212<DT><SAMP>‘--keep-header’</SAMP> 1213<DD> 1214<A NAME="IDX687"></A> 1215Keep the header entry, i.e. the message with <SAMP>‘msgid ""’</SAMP>, unmodified, 1216instead of filtering it. By default, the header entry is subject to 1217filtering like any other message. 1218 1219<DT><SAMP>‘--no-location’</SAMP> 1220<DD> 1221<A NAME="IDX688"></A> 1222Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 1223 1224<DT><SAMP>‘--add-location’</SAMP> 1225<DD> 1226<A NAME="IDX689"></A> 1227Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 1228 1229<DT><SAMP>‘--strict’</SAMP> 1230<DD> 1231<A NAME="IDX690"></A> 1232Write out a strict Uniforum conforming PO file. Note that this 1233Uniforum format should be avoided because it doesn't support the 1234GNU extensions. 1235 1236<DT><SAMP>‘-p’</SAMP> 1237<DD> 1238<DT><SAMP>‘--properties-output’</SAMP> 1239<DD> 1240<A NAME="IDX691"></A> 1241<A NAME="IDX692"></A> 1242Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 1243that this file format doesn't support plural forms and silently drops 1244obsolete messages. 1245 1246<DT><SAMP>‘--stringtable-output’</SAMP> 1247<DD> 1248<A NAME="IDX693"></A> 1249Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 1250Note that this file format doesn't support plural forms. 1251 1252<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 1253<DD> 1254<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 1255<DD> 1256<A NAME="IDX694"></A> 1257<A NAME="IDX695"></A> 1258Set the output page width. Long strings in the output files will be 1259split across multiple lines in order to ensure that each line's width 1260(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 1261 1262<DT><SAMP>‘--no-wrap’</SAMP> 1263<DD> 1264<A NAME="IDX696"></A> 1265Do not break long message lines. Message lines whose width exceeds the 1266output page width will not be split into several lines. Only file reference 1267lines which are wider than the output page width will be split. 1268 1269<DT><SAMP>‘-s’</SAMP> 1270<DD> 1271<DT><SAMP>‘--sort-output’</SAMP> 1272<DD> 1273<A NAME="IDX697"></A> 1274<A NAME="IDX698"></A> 1275Generate sorted output. Note that using this option makes it much harder 1276for the translator to understand each message's context. 1277 1278<DT><SAMP>‘-F’</SAMP> 1279<DD> 1280<DT><SAMP>‘--sort-by-file’</SAMP> 1281<DD> 1282<A NAME="IDX699"></A> 1283<A NAME="IDX700"></A> 1284Sort output by file location. 1285 1286</DL> 1287 1288 1289 1290<H3><A NAME="SEC110" HREF="gettext_toc.html#TOC110">9.4.8 Informative output</A></H3> 1291 1292<DL COMPACT> 1293 1294<DT><SAMP>‘-h’</SAMP> 1295<DD> 1296<DT><SAMP>‘--help’</SAMP> 1297<DD> 1298<A NAME="IDX701"></A> 1299<A NAME="IDX702"></A> 1300Display this help and exit. 1301 1302<DT><SAMP>‘-V’</SAMP> 1303<DD> 1304<DT><SAMP>‘--version’</SAMP> 1305<DD> 1306<A NAME="IDX703"></A> 1307<A NAME="IDX704"></A> 1308Output version information and exit. 1309 1310</DL> 1311 1312 1313 1314<H3><A NAME="SEC111" HREF="gettext_toc.html#TOC111">9.4.9 Examples</A></H3> 1315 1316<P> 1317To convert German translations to Swiss orthography (in an UTF-8 locale): 1318 1319</P> 1320 1321<PRE> 1322msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g' 1323</PRE> 1324 1325<P> 1326To convert Serbian translations in Cyrillic script to Latin script: 1327 1328</P> 1329 1330<PRE> 1331msgfilter recode-sr-latin sr.po 1332</PRE> 1333 1334 1335 1336<H2><A NAME="SEC112" HREF="gettext_toc.html#TOC112">9.5 Invoking the <CODE>msguniq</CODE> Program</A></H2> 1337 1338<P> 1339<A NAME="IDX705"></A> 1340<A NAME="IDX706"></A> 1341 1342<PRE> 1343msguniq [<VAR>option</VAR>] [<VAR>inputfile</VAR>] 1344</PRE> 1345 1346<P> 1347<A NAME="IDX707"></A> 1348<A NAME="IDX708"></A> 1349The <CODE>msguniq</CODE> program unifies duplicate translations in a translation 1350catalog. It finds duplicate translations of the same message ID. Such 1351duplicates are invalid input for other programs like <CODE>msgfmt</CODE>, 1352<CODE>msgmerge</CODE> or <CODE>msgcat</CODE>. By default, duplicates are merged 1353together. When using the <SAMP>‘--repeated’</SAMP> option, only duplicates are 1354output, and all other messages are discarded. Comments and extracted 1355comments will be cumulated, except that if <SAMP>‘--use-first’</SAMP> is 1356specified, they will be taken from the first translation. File positions 1357will be cumulated. When using the <SAMP>‘--unique’</SAMP> option, duplicates are 1358discarded. 1359 1360</P> 1361 1362 1363<H3><A NAME="SEC113" HREF="gettext_toc.html#TOC113">9.5.1 Input file location</A></H3> 1364 1365<DL COMPACT> 1366 1367<DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP> 1368<DD> 1369Input PO file. 1370 1371<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 1372<DD> 1373<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 1374<DD> 1375<A NAME="IDX709"></A> 1376<A NAME="IDX710"></A> 1377Add <VAR>directory</VAR> to the list of directories. Source files are 1378searched relative to this list of directories. The resulting <TT>‘.po’</TT> 1379file will be written relative to the current directory, though. 1380 1381</DL> 1382 1383<P> 1384If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read. 1385 1386</P> 1387 1388 1389<H3><A NAME="SEC114" HREF="gettext_toc.html#TOC114">9.5.2 Output file location</A></H3> 1390 1391<DL COMPACT> 1392 1393<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 1394<DD> 1395<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 1396<DD> 1397<A NAME="IDX711"></A> 1398<A NAME="IDX712"></A> 1399Write output to specified file. 1400 1401</DL> 1402 1403<P> 1404The results are written to standard output if no output file is specified 1405or if it is <SAMP>‘-’</SAMP>. 1406 1407</P> 1408 1409 1410<H3><A NAME="SEC115" HREF="gettext_toc.html#TOC115">9.5.3 Message selection</A></H3> 1411 1412<DL COMPACT> 1413 1414<DT><SAMP>‘-d’</SAMP> 1415<DD> 1416<DT><SAMP>‘--repeated’</SAMP> 1417<DD> 1418<A NAME="IDX713"></A> 1419<A NAME="IDX714"></A> 1420Print only duplicates. 1421 1422<DT><SAMP>‘-u’</SAMP> 1423<DD> 1424<DT><SAMP>‘--unique’</SAMP> 1425<DD> 1426<A NAME="IDX715"></A> 1427<A NAME="IDX716"></A> 1428Print only unique messages, discard duplicates. 1429 1430</DL> 1431 1432 1433 1434<H3><A NAME="SEC116" HREF="gettext_toc.html#TOC116">9.5.4 Input file syntax</A></H3> 1435 1436<DL COMPACT> 1437 1438<DT><SAMP>‘-P’</SAMP> 1439<DD> 1440<DT><SAMP>‘--properties-input’</SAMP> 1441<DD> 1442<A NAME="IDX717"></A> 1443<A NAME="IDX718"></A> 1444Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> 1445syntax, not in PO file syntax. 1446 1447<DT><SAMP>‘--stringtable-input’</SAMP> 1448<DD> 1449<A NAME="IDX719"></A> 1450Assume the input file is a NeXTstep/GNUstep localized resource file in 1451<CODE>.strings</CODE> syntax, not in PO file syntax. 1452 1453</DL> 1454 1455 1456 1457<H3><A NAME="SEC117" HREF="gettext_toc.html#TOC117">9.5.5 Output details</A></H3> 1458 1459<DL COMPACT> 1460 1461<DT><SAMP>‘-t’</SAMP> 1462<DD> 1463<DT><SAMP>‘--to-code=<VAR>name</VAR>’</SAMP> 1464<DD> 1465<A NAME="IDX720"></A> 1466<A NAME="IDX721"></A> 1467Specify encoding for output. 1468 1469<DT><SAMP>‘--use-first’</SAMP> 1470<DD> 1471<A NAME="IDX722"></A> 1472Use first available translation for each message. Don't merge several 1473translations into one. 1474 1475<DT><SAMP>‘--force-po’</SAMP> 1476<DD> 1477<A NAME="IDX723"></A> 1478Always write an output file even if it contains no message. 1479 1480<DT><SAMP>‘-i’</SAMP> 1481<DD> 1482<DT><SAMP>‘--indent’</SAMP> 1483<DD> 1484<A NAME="IDX724"></A> 1485<A NAME="IDX725"></A> 1486Write the .po file using indented style. 1487 1488<DT><SAMP>‘--no-location’</SAMP> 1489<DD> 1490<A NAME="IDX726"></A> 1491Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 1492 1493<DT><SAMP>‘-n’</SAMP> 1494<DD> 1495<DT><SAMP>‘--add-location’</SAMP> 1496<DD> 1497<A NAME="IDX727"></A> 1498<A NAME="IDX728"></A> 1499Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 1500 1501<DT><SAMP>‘--strict’</SAMP> 1502<DD> 1503<A NAME="IDX729"></A> 1504Write out a strict Uniforum conforming PO file. Note that this 1505Uniforum format should be avoided because it doesn't support the 1506GNU extensions. 1507 1508<DT><SAMP>‘-p’</SAMP> 1509<DD> 1510<DT><SAMP>‘--properties-output’</SAMP> 1511<DD> 1512<A NAME="IDX730"></A> 1513<A NAME="IDX731"></A> 1514Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 1515that this file format doesn't support plural forms and silently drops 1516obsolete messages. 1517 1518<DT><SAMP>‘--stringtable-output’</SAMP> 1519<DD> 1520<A NAME="IDX732"></A> 1521Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 1522Note that this file format doesn't support plural forms. 1523 1524<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 1525<DD> 1526<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 1527<DD> 1528<A NAME="IDX733"></A> 1529<A NAME="IDX734"></A> 1530Set the output page width. Long strings in the output files will be 1531split across multiple lines in order to ensure that each line's width 1532(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 1533 1534<DT><SAMP>‘--no-wrap’</SAMP> 1535<DD> 1536<A NAME="IDX735"></A> 1537Do not break long message lines. Message lines whose width exceeds the 1538output page width will not be split into several lines. Only file reference 1539lines which are wider than the output page width will be split. 1540 1541<DT><SAMP>‘-s’</SAMP> 1542<DD> 1543<DT><SAMP>‘--sort-output’</SAMP> 1544<DD> 1545<A NAME="IDX736"></A> 1546<A NAME="IDX737"></A> 1547Generate sorted output. Note that using this option makes it much harder 1548for the translator to understand each message's context. 1549 1550<DT><SAMP>‘-F’</SAMP> 1551<DD> 1552<DT><SAMP>‘--sort-by-file’</SAMP> 1553<DD> 1554<A NAME="IDX738"></A> 1555<A NAME="IDX739"></A> 1556Sort output by file location. 1557 1558</DL> 1559 1560 1561 1562<H3><A NAME="SEC118" HREF="gettext_toc.html#TOC118">9.5.6 Informative output</A></H3> 1563 1564<DL COMPACT> 1565 1566<DT><SAMP>‘-h’</SAMP> 1567<DD> 1568<DT><SAMP>‘--help’</SAMP> 1569<DD> 1570<A NAME="IDX740"></A> 1571<A NAME="IDX741"></A> 1572Display this help and exit. 1573 1574<DT><SAMP>‘-V’</SAMP> 1575<DD> 1576<DT><SAMP>‘--version’</SAMP> 1577<DD> 1578<A NAME="IDX742"></A> 1579<A NAME="IDX743"></A> 1580Output version information and exit. 1581 1582</DL> 1583 1584 1585 1586<H2><A NAME="SEC119" HREF="gettext_toc.html#TOC119">9.6 Invoking the <CODE>msgcomm</CODE> Program</A></H2> 1587 1588<P> 1589<A NAME="IDX744"></A> 1590<A NAME="IDX745"></A> 1591 1592<PRE> 1593msgcomm [<VAR>option</VAR>] [<VAR>inputfile</VAR>]... 1594</PRE> 1595 1596<P> 1597<A NAME="IDX746"></A> 1598The <CODE>msgcomm</CODE> program finds messages which are common to two or more 1599of the specified PO files. 1600By using the <CODE>--more-than</CODE> option, greater commonality may be requested 1601before messages are printed. Conversely, the <CODE>--less-than</CODE> option may be 1602used to specify less commonality before messages are printed (i.e. 1603<SAMP>‘--less-than=2’</SAMP> will only print the unique messages). Translations, 1604comments and extract comments will be preserved, but only from the first 1605PO file to define them. File positions from all PO files will be 1606cumulated. 1607 1608</P> 1609 1610 1611<H3><A NAME="SEC120" HREF="gettext_toc.html#TOC120">9.6.1 Input file location</A></H3> 1612 1613<DL COMPACT> 1614 1615<DT><SAMP>‘<VAR>inputfile</VAR> ...’</SAMP> 1616<DD> 1617Input files. 1618 1619<DT><SAMP>‘-f <VAR>file</VAR>’</SAMP> 1620<DD> 1621<DT><SAMP>‘--files-from=<VAR>file</VAR>’</SAMP> 1622<DD> 1623<A NAME="IDX747"></A> 1624<A NAME="IDX748"></A> 1625Read the names of the input files from <VAR>file</VAR> instead of getting 1626them from the command line. 1627 1628<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 1629<DD> 1630<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 1631<DD> 1632<A NAME="IDX749"></A> 1633<A NAME="IDX750"></A> 1634Add <VAR>directory</VAR> to the list of directories. Source files are 1635searched relative to this list of directories. The resulting <TT>‘.po’</TT> 1636file will be written relative to the current directory, though. 1637 1638</DL> 1639 1640<P> 1641If <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read. 1642 1643</P> 1644 1645 1646<H3><A NAME="SEC121" HREF="gettext_toc.html#TOC121">9.6.2 Output file location</A></H3> 1647 1648<DL COMPACT> 1649 1650<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 1651<DD> 1652<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 1653<DD> 1654<A NAME="IDX751"></A> 1655<A NAME="IDX752"></A> 1656Write output to specified file. 1657 1658</DL> 1659 1660<P> 1661The results are written to standard output if no output file is specified 1662or if it is <SAMP>‘-’</SAMP>. 1663 1664</P> 1665 1666 1667<H3><A NAME="SEC122" HREF="gettext_toc.html#TOC122">9.6.3 Message selection</A></H3> 1668 1669<DL COMPACT> 1670 1671<DT><SAMP>‘-< <VAR>number</VAR>’</SAMP> 1672<DD> 1673<DT><SAMP>‘--less-than=<VAR>number</VAR>’</SAMP> 1674<DD> 1675<A NAME="IDX753"></A> 1676<A NAME="IDX754"></A> 1677Print messages with less than <VAR>number</VAR> definitions, defaults to infinite 1678if not set. 1679 1680<DT><SAMP>‘-> <VAR>number</VAR>’</SAMP> 1681<DD> 1682<DT><SAMP>‘--more-than=<VAR>number</VAR>’</SAMP> 1683<DD> 1684<A NAME="IDX755"></A> 1685<A NAME="IDX756"></A> 1686Print messages with more than <VAR>number</VAR> definitions, defaults to 1 if not 1687set. 1688 1689<DT><SAMP>‘-u’</SAMP> 1690<DD> 1691<DT><SAMP>‘--unique’</SAMP> 1692<DD> 1693<A NAME="IDX757"></A> 1694<A NAME="IDX758"></A> 1695Shorthand for <SAMP>‘--less-than=2’</SAMP>. Requests that only unique messages be 1696printed. 1697 1698</DL> 1699 1700 1701 1702<H3><A NAME="SEC123" HREF="gettext_toc.html#TOC123">9.6.4 Input file syntax</A></H3> 1703 1704<DL COMPACT> 1705 1706<DT><SAMP>‘-P’</SAMP> 1707<DD> 1708<DT><SAMP>‘--properties-input’</SAMP> 1709<DD> 1710<A NAME="IDX759"></A> 1711<A NAME="IDX760"></A> 1712Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE> 1713syntax, not in PO file syntax. 1714 1715<DT><SAMP>‘--stringtable-input’</SAMP> 1716<DD> 1717<A NAME="IDX761"></A> 1718Assume the input files are NeXTstep/GNUstep localized resource files in 1719<CODE>.strings</CODE> syntax, not in PO file syntax. 1720 1721</DL> 1722 1723 1724 1725<H3><A NAME="SEC124" HREF="gettext_toc.html#TOC124">9.6.5 Output details</A></H3> 1726 1727<DL COMPACT> 1728 1729<DT><SAMP>‘--force-po’</SAMP> 1730<DD> 1731<A NAME="IDX762"></A> 1732Always write an output file even if it contains no message. 1733 1734<DT><SAMP>‘-i’</SAMP> 1735<DD> 1736<DT><SAMP>‘--indent’</SAMP> 1737<DD> 1738<A NAME="IDX763"></A> 1739<A NAME="IDX764"></A> 1740Write the .po file using indented style. 1741 1742<DT><SAMP>‘--no-location’</SAMP> 1743<DD> 1744<A NAME="IDX765"></A> 1745Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 1746 1747<DT><SAMP>‘-n’</SAMP> 1748<DD> 1749<DT><SAMP>‘--add-location’</SAMP> 1750<DD> 1751<A NAME="IDX766"></A> 1752<A NAME="IDX767"></A> 1753Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 1754 1755<DT><SAMP>‘--strict’</SAMP> 1756<DD> 1757<A NAME="IDX768"></A> 1758Write out a strict Uniforum conforming PO file. Note that this 1759Uniforum format should be avoided because it doesn't support the 1760GNU extensions. 1761 1762<DT><SAMP>‘-p’</SAMP> 1763<DD> 1764<DT><SAMP>‘--properties-output’</SAMP> 1765<DD> 1766<A NAME="IDX769"></A> 1767<A NAME="IDX770"></A> 1768Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 1769that this file format doesn't support plural forms and silently drops 1770obsolete messages. 1771 1772<DT><SAMP>‘--stringtable-output’</SAMP> 1773<DD> 1774<A NAME="IDX771"></A> 1775Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 1776Note that this file format doesn't support plural forms. 1777 1778<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 1779<DD> 1780<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 1781<DD> 1782<A NAME="IDX772"></A> 1783<A NAME="IDX773"></A> 1784Set the output page width. Long strings in the output files will be 1785split across multiple lines in order to ensure that each line's width 1786(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 1787 1788<DT><SAMP>‘--no-wrap’</SAMP> 1789<DD> 1790<A NAME="IDX774"></A> 1791Do not break long message lines. Message lines whose width exceeds the 1792output page width will not be split into several lines. Only file reference 1793lines which are wider than the output page width will be split. 1794 1795<DT><SAMP>‘-s’</SAMP> 1796<DD> 1797<DT><SAMP>‘--sort-output’</SAMP> 1798<DD> 1799<A NAME="IDX775"></A> 1800<A NAME="IDX776"></A> 1801Generate sorted output. Note that using this option makes it much harder 1802for the translator to understand each message's context. 1803 1804<DT><SAMP>‘-F’</SAMP> 1805<DD> 1806<DT><SAMP>‘--sort-by-file’</SAMP> 1807<DD> 1808<A NAME="IDX777"></A> 1809<A NAME="IDX778"></A> 1810Sort output by file location. 1811 1812<DT><SAMP>‘--omit-header’</SAMP> 1813<DD> 1814<A NAME="IDX779"></A> 1815Don't write header with <SAMP>‘msgid ""’</SAMP> entry. 1816 1817</DL> 1818 1819 1820 1821<H3><A NAME="SEC125" HREF="gettext_toc.html#TOC125">9.6.6 Informative output</A></H3> 1822 1823<DL COMPACT> 1824 1825<DT><SAMP>‘-h’</SAMP> 1826<DD> 1827<DT><SAMP>‘--help’</SAMP> 1828<DD> 1829<A NAME="IDX780"></A> 1830<A NAME="IDX781"></A> 1831Display this help and exit. 1832 1833<DT><SAMP>‘-V’</SAMP> 1834<DD> 1835<DT><SAMP>‘--version’</SAMP> 1836<DD> 1837<A NAME="IDX782"></A> 1838<A NAME="IDX783"></A> 1839Output version information and exit. 1840 1841</DL> 1842 1843 1844 1845<H2><A NAME="SEC126" HREF="gettext_toc.html#TOC126">9.7 Invoking the <CODE>msgcmp</CODE> Program</A></H2> 1846 1847<P> 1848<A NAME="IDX784"></A> 1849<A NAME="IDX785"></A> 1850 1851<PRE> 1852msgcmp [<VAR>option</VAR>] <VAR>def</VAR>.po <VAR>ref</VAR>.pot 1853</PRE> 1854 1855<P> 1856<A NAME="IDX786"></A> 1857The <CODE>msgcmp</CODE> program compares two Uniforum style .po files to check that 1858both contain the same set of msgid strings. The <VAR>def</VAR>.po file is an 1859existing PO file with the translations. The <VAR>ref</VAR>.pot file is the last 1860created PO file, or a PO Template file (generally created by <CODE>xgettext</CODE>). 1861This is useful for checking that you have translated each and every message 1862in your program. Where an exact match cannot be found, fuzzy matching is 1863used to produce better diagnostics. 1864 1865</P> 1866 1867 1868<H3><A NAME="SEC127" HREF="gettext_toc.html#TOC127">9.7.1 Input file location</A></H3> 1869 1870<DL COMPACT> 1871 1872<DT><SAMP>‘<VAR>def</VAR>.po’</SAMP> 1873<DD> 1874Translations. 1875 1876<DT><SAMP>‘<VAR>ref</VAR>.pot’</SAMP> 1877<DD> 1878References to the sources. 1879 1880<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 1881<DD> 1882<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 1883<DD> 1884<A NAME="IDX787"></A> 1885<A NAME="IDX788"></A> 1886Add <VAR>directory</VAR> to the list of directories. Source files are 1887searched relative to this list of directories. 1888 1889</DL> 1890 1891 1892 1893<H3><A NAME="SEC128" HREF="gettext_toc.html#TOC128">9.7.2 Operation modifiers</A></H3> 1894 1895<DL COMPACT> 1896 1897<DT><SAMP>‘-m’</SAMP> 1898<DD> 1899<DT><SAMP>‘--multi-domain’</SAMP> 1900<DD> 1901<A NAME="IDX789"></A> 1902<A NAME="IDX790"></A> 1903Apply <VAR>ref</VAR>.pot to each of the domains in <VAR>def</VAR>.po. 1904 1905<DT><SAMP>‘--use-fuzzy’</SAMP> 1906<DD> 1907<A NAME="IDX791"></A> 1908Consider fuzzy messages in the <VAR>def</VAR>.po file like translated messages. 1909Note that using this option is usually wrong, because fuzzy messages are 1910exactly those which have not been validated by a human translator. 1911 1912<DT><SAMP>‘--use-untranslated’</SAMP> 1913<DD> 1914<A NAME="IDX792"></A> 1915Consider untranslated messages in the <VAR>def</VAR>.po file like translated 1916messages. Note that using this option is usually wrong. 1917 1918</DL> 1919 1920 1921 1922<H3><A NAME="SEC129" HREF="gettext_toc.html#TOC129">9.7.3 Input file syntax</A></H3> 1923 1924<DL COMPACT> 1925 1926<DT><SAMP>‘-P’</SAMP> 1927<DD> 1928<DT><SAMP>‘--properties-input’</SAMP> 1929<DD> 1930<A NAME="IDX793"></A> 1931<A NAME="IDX794"></A> 1932Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE> 1933syntax, not in PO file syntax. 1934 1935<DT><SAMP>‘--stringtable-input’</SAMP> 1936<DD> 1937<A NAME="IDX795"></A> 1938Assume the input files are NeXTstep/GNUstep localized resource files in 1939<CODE>.strings</CODE> syntax, not in PO file syntax. 1940 1941</DL> 1942 1943 1944 1945<H3><A NAME="SEC130" HREF="gettext_toc.html#TOC130">9.7.4 Informative output</A></H3> 1946 1947<DL COMPACT> 1948 1949<DT><SAMP>‘-h’</SAMP> 1950<DD> 1951<DT><SAMP>‘--help’</SAMP> 1952<DD> 1953<A NAME="IDX796"></A> 1954<A NAME="IDX797"></A> 1955Display this help and exit. 1956 1957<DT><SAMP>‘-V’</SAMP> 1958<DD> 1959<DT><SAMP>‘--version’</SAMP> 1960<DD> 1961<A NAME="IDX798"></A> 1962<A NAME="IDX799"></A> 1963Output version information and exit. 1964 1965</DL> 1966 1967 1968 1969<H2><A NAME="SEC131" HREF="gettext_toc.html#TOC131">9.8 Invoking the <CODE>msgattrib</CODE> Program</A></H2> 1970 1971<P> 1972<A NAME="IDX800"></A> 1973<A NAME="IDX801"></A> 1974 1975<PRE> 1976msgattrib [<VAR>option</VAR>] [<VAR>inputfile</VAR>] 1977</PRE> 1978 1979<P> 1980<A NAME="IDX802"></A> 1981<A NAME="IDX803"></A> 1982The <CODE>msgattrib</CODE> program filters the messages of a translation catalog 1983according to their attributes, and manipulates the attributes. 1984 1985</P> 1986 1987 1988<H3><A NAME="SEC132" HREF="gettext_toc.html#TOC132">9.8.1 Input file location</A></H3> 1989 1990<DL COMPACT> 1991 1992<DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP> 1993<DD> 1994Input PO file. 1995 1996<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 1997<DD> 1998<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 1999<DD> 2000<A NAME="IDX804"></A> 2001<A NAME="IDX805"></A> 2002Add <VAR>directory</VAR> to the list of directories. Source files are 2003searched relative to this list of directories. The resulting <TT>‘.po’</TT> 2004file will be written relative to the current directory, though. 2005 2006</DL> 2007 2008<P> 2009If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read. 2010 2011</P> 2012 2013 2014<H3><A NAME="SEC133" HREF="gettext_toc.html#TOC133">9.8.2 Output file location</A></H3> 2015 2016<DL COMPACT> 2017 2018<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 2019<DD> 2020<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 2021<DD> 2022<A NAME="IDX806"></A> 2023<A NAME="IDX807"></A> 2024Write output to specified file. 2025 2026</DL> 2027 2028<P> 2029The results are written to standard output if no output file is specified 2030or if it is <SAMP>‘-’</SAMP>. 2031 2032</P> 2033 2034 2035<H3><A NAME="SEC134" HREF="gettext_toc.html#TOC134">9.8.3 Message selection</A></H3> 2036 2037<DL COMPACT> 2038 2039<DT><SAMP>‘--translated’</SAMP> 2040<DD> 2041<A NAME="IDX808"></A> 2042Keep translated messages, remove untranslated messages. 2043 2044<DT><SAMP>‘--untranslated’</SAMP> 2045<DD> 2046<A NAME="IDX809"></A> 2047Keep untranslated messages, remove translated messages. 2048 2049<DT><SAMP>‘--no-fuzzy’</SAMP> 2050<DD> 2051<A NAME="IDX810"></A> 2052Remove 2053���fuzzy��� 2054marked messages. 2055 2056<DT><SAMP>‘--only-fuzzy’</SAMP> 2057<DD> 2058<A NAME="IDX811"></A> 2059Keep 2060���fuzzy��� 2061marked messages, remove all other messages. 2062 2063<DT><SAMP>‘--no-obsolete’</SAMP> 2064<DD> 2065<A NAME="IDX812"></A> 2066Remove obsolete #~ messages. 2067 2068<DT><SAMP>‘--only-obsolete’</SAMP> 2069<DD> 2070<A NAME="IDX813"></A> 2071Keep obsolete #~ messages, remove all other messages. 2072 2073</DL> 2074 2075 2076 2077<H3><A NAME="SEC135" HREF="gettext_toc.html#TOC135">9.8.4 Attribute manipulation</A></H3> 2078 2079<P> 2080<A NAME="IDX814"></A> 2081Attributes are modified after the message selection/removal has been 2082performed. If the <SAMP>‘--only-file’</SAMP> or <SAMP>‘--ignore-file’</SAMP> option is 2083specified, the attribute modification is applied only to those messages 2084that are listed in the <VAR>only-file</VAR> and not listed in the 2085<VAR>ignore-file</VAR>. 2086 2087</P> 2088<DL COMPACT> 2089 2090<DT><SAMP>‘--set-fuzzy’</SAMP> 2091<DD> 2092<A NAME="IDX815"></A> 2093Set all messages 2094���fuzzy���. 2095 2096<DT><SAMP>‘--clear-fuzzy’</SAMP> 2097<DD> 2098<A NAME="IDX816"></A> 2099Set all messages 2100non-���fuzzy���. 2101 2102<DT><SAMP>‘--set-obsolete’</SAMP> 2103<DD> 2104<A NAME="IDX817"></A> 2105Set all messages obsolete. 2106 2107<DT><SAMP>‘--clear-obsolete’</SAMP> 2108<DD> 2109<A NAME="IDX818"></A> 2110Set all messages non-obsolete. 2111 2112<DT><SAMP>‘--clear-previous’</SAMP> 2113<DD> 2114<A NAME="IDX819"></A> 2115Remove the ���previous msgid��� (<SAMP>‘#|’</SAMP>) comments from all messages. 2116 2117<DT><SAMP>‘--only-file=<VAR>file</VAR>’</SAMP> 2118<DD> 2119<A NAME="IDX820"></A> 2120Limit the attribute changes to entries that are listed in <VAR>file</VAR>. 2121<VAR>file</VAR> should be a PO or POT file. 2122 2123<DT><SAMP>‘--ignore-file=<VAR>file</VAR>’</SAMP> 2124<DD> 2125<A NAME="IDX821"></A> 2126Limit the attribute changes to entries that are not listed in <VAR>file</VAR>. 2127<VAR>file</VAR> should be a PO or POT file. 2128 2129<DT><SAMP>‘--fuzzy’</SAMP> 2130<DD> 2131<A NAME="IDX822"></A> 2132Synonym for <SAMP>‘--only-fuzzy --clear-fuzzy’</SAMP>: It keeps only the fuzzy 2133messages and removes their 2134���fuzzy��� 2135mark. 2136 2137<DT><SAMP>‘--obsolete’</SAMP> 2138<DD> 2139<A NAME="IDX823"></A> 2140Synonym for <SAMP>‘--only-obsolete --clear-obsolete’</SAMP>: It keeps only the 2141obsolete messages and makes them non-obsolete. 2142 2143</DL> 2144 2145 2146 2147<H3><A NAME="SEC136" HREF="gettext_toc.html#TOC136">9.8.5 Input file syntax</A></H3> 2148 2149<DL COMPACT> 2150 2151<DT><SAMP>‘-P’</SAMP> 2152<DD> 2153<DT><SAMP>‘--properties-input’</SAMP> 2154<DD> 2155<A NAME="IDX824"></A> 2156<A NAME="IDX825"></A> 2157Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> 2158syntax, not in PO file syntax. 2159 2160<DT><SAMP>‘--stringtable-input’</SAMP> 2161<DD> 2162<A NAME="IDX826"></A> 2163Assume the input file is a NeXTstep/GNUstep localized resource file in 2164<CODE>.strings</CODE> syntax, not in PO file syntax. 2165 2166</DL> 2167 2168 2169 2170<H3><A NAME="SEC137" HREF="gettext_toc.html#TOC137">9.8.6 Output details</A></H3> 2171 2172<DL COMPACT> 2173 2174<DT><SAMP>‘--force-po’</SAMP> 2175<DD> 2176<A NAME="IDX827"></A> 2177Always write an output file even if it contains no message. 2178 2179<DT><SAMP>‘-i’</SAMP> 2180<DD> 2181<DT><SAMP>‘--indent’</SAMP> 2182<DD> 2183<A NAME="IDX828"></A> 2184<A NAME="IDX829"></A> 2185Write the .po file using indented style. 2186 2187<DT><SAMP>‘--no-location’</SAMP> 2188<DD> 2189<A NAME="IDX830"></A> 2190Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 2191 2192<DT><SAMP>‘-n’</SAMP> 2193<DD> 2194<DT><SAMP>‘--add-location’</SAMP> 2195<DD> 2196<A NAME="IDX831"></A> 2197<A NAME="IDX832"></A> 2198Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 2199 2200<DT><SAMP>‘--strict’</SAMP> 2201<DD> 2202<A NAME="IDX833"></A> 2203Write out a strict Uniforum conforming PO file. Note that this 2204Uniforum format should be avoided because it doesn't support the 2205GNU extensions. 2206 2207<DT><SAMP>‘-p’</SAMP> 2208<DD> 2209<DT><SAMP>‘--properties-output’</SAMP> 2210<DD> 2211<A NAME="IDX834"></A> 2212<A NAME="IDX835"></A> 2213Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 2214that this file format doesn't support plural forms and silently drops 2215obsolete messages. 2216 2217<DT><SAMP>‘--stringtable-output’</SAMP> 2218<DD> 2219<A NAME="IDX836"></A> 2220Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 2221Note that this file format doesn't support plural forms. 2222 2223<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 2224<DD> 2225<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 2226<DD> 2227<A NAME="IDX837"></A> 2228<A NAME="IDX838"></A> 2229Set the output page width. Long strings in the output files will be 2230split across multiple lines in order to ensure that each line's width 2231(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 2232 2233<DT><SAMP>‘--no-wrap’</SAMP> 2234<DD> 2235<A NAME="IDX839"></A> 2236Do not break long message lines. Message lines whose width exceeds the 2237output page width will not be split into several lines. Only file reference 2238lines which are wider than the output page width will be split. 2239 2240<DT><SAMP>‘-s’</SAMP> 2241<DD> 2242<DT><SAMP>‘--sort-output’</SAMP> 2243<DD> 2244<A NAME="IDX840"></A> 2245<A NAME="IDX841"></A> 2246Generate sorted output. Note that using this option makes it much harder 2247for the translator to understand each message's context. 2248 2249<DT><SAMP>‘-F’</SAMP> 2250<DD> 2251<DT><SAMP>‘--sort-by-file’</SAMP> 2252<DD> 2253<A NAME="IDX842"></A> 2254<A NAME="IDX843"></A> 2255Sort output by file location. 2256 2257</DL> 2258 2259 2260 2261<H3><A NAME="SEC138" HREF="gettext_toc.html#TOC138">9.8.7 Informative output</A></H3> 2262 2263<DL COMPACT> 2264 2265<DT><SAMP>‘-h’</SAMP> 2266<DD> 2267<DT><SAMP>‘--help’</SAMP> 2268<DD> 2269<A NAME="IDX844"></A> 2270<A NAME="IDX845"></A> 2271Display this help and exit. 2272 2273<DT><SAMP>‘-V’</SAMP> 2274<DD> 2275<DT><SAMP>‘--version’</SAMP> 2276<DD> 2277<A NAME="IDX846"></A> 2278<A NAME="IDX847"></A> 2279Output version information and exit. 2280 2281</DL> 2282 2283 2284 2285<H2><A NAME="SEC139" HREF="gettext_toc.html#TOC139">9.9 Invoking the <CODE>msgen</CODE> Program</A></H2> 2286 2287<P> 2288<A NAME="IDX848"></A> 2289<A NAME="IDX849"></A> 2290 2291<PRE> 2292msgen [<VAR>option</VAR>] <VAR>inputfile</VAR> 2293</PRE> 2294 2295<P> 2296<A NAME="IDX850"></A> 2297The <CODE>msgen</CODE> program creates an English translation catalog. The 2298input file is the last created English PO file, or a PO Template file 2299(generally created by xgettext). Untranslated entries are assigned a 2300translation that is identical to the msgid. 2301 2302</P> 2303<P> 2304Note: <SAMP>‘msginit --no-translator --locale=en’</SAMP> performs a very similar 2305task. The main difference is that <CODE>msginit</CODE> cares specially about 2306the header entry, whereas <CODE>msgen</CODE> doesn't. 2307 2308</P> 2309 2310 2311<H3><A NAME="SEC140" HREF="gettext_toc.html#TOC140">9.9.1 Input file location</A></H3> 2312 2313<DL COMPACT> 2314 2315<DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP> 2316<DD> 2317Input PO or POT file. 2318 2319<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 2320<DD> 2321<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 2322<DD> 2323<A NAME="IDX851"></A> 2324<A NAME="IDX852"></A> 2325Add <VAR>directory</VAR> to the list of directories. Source files are 2326searched relative to this list of directories. The resulting <TT>‘.po’</TT> 2327file will be written relative to the current directory, though. 2328 2329</DL> 2330 2331<P> 2332If <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read. 2333 2334</P> 2335 2336 2337<H3><A NAME="SEC141" HREF="gettext_toc.html#TOC141">9.9.2 Output file location</A></H3> 2338 2339<DL COMPACT> 2340 2341<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 2342<DD> 2343<DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP> 2344<DD> 2345<A NAME="IDX853"></A> 2346<A NAME="IDX854"></A> 2347Write output to specified file. 2348 2349</DL> 2350 2351<P> 2352The results are written to standard output if no output file is specified 2353or if it is <SAMP>‘-’</SAMP>. 2354 2355</P> 2356 2357 2358<H3><A NAME="SEC142" HREF="gettext_toc.html#TOC142">9.9.3 Input file syntax</A></H3> 2359 2360<DL COMPACT> 2361 2362<DT><SAMP>‘-P’</SAMP> 2363<DD> 2364<DT><SAMP>‘--properties-input’</SAMP> 2365<DD> 2366<A NAME="IDX855"></A> 2367<A NAME="IDX856"></A> 2368Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> 2369syntax, not in PO file syntax. 2370 2371<DT><SAMP>‘--stringtable-input’</SAMP> 2372<DD> 2373<A NAME="IDX857"></A> 2374Assume the input file is a NeXTstep/GNUstep localized resource file in 2375<CODE>.strings</CODE> syntax, not in PO file syntax. 2376 2377</DL> 2378 2379 2380 2381<H3><A NAME="SEC143" HREF="gettext_toc.html#TOC143">9.9.4 Output details</A></H3> 2382 2383<DL COMPACT> 2384 2385<DT><SAMP>‘--force-po’</SAMP> 2386<DD> 2387<A NAME="IDX858"></A> 2388Always write an output file even if it contains no message. 2389 2390<DT><SAMP>‘-i’</SAMP> 2391<DD> 2392<DT><SAMP>‘--indent’</SAMP> 2393<DD> 2394<A NAME="IDX859"></A> 2395<A NAME="IDX860"></A> 2396Write the .po file using indented style. 2397 2398<DT><SAMP>‘--no-location’</SAMP> 2399<DD> 2400<A NAME="IDX861"></A> 2401Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 2402 2403<DT><SAMP>‘--add-location’</SAMP> 2404<DD> 2405<A NAME="IDX862"></A> 2406Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 2407 2408<DT><SAMP>‘--strict’</SAMP> 2409<DD> 2410<A NAME="IDX863"></A> 2411Write out a strict Uniforum conforming PO file. Note that this 2412Uniforum format should be avoided because it doesn't support the 2413GNU extensions. 2414 2415<DT><SAMP>‘-p’</SAMP> 2416<DD> 2417<DT><SAMP>‘--properties-output’</SAMP> 2418<DD> 2419<A NAME="IDX864"></A> 2420<A NAME="IDX865"></A> 2421Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 2422that this file format doesn't support plural forms and silently drops 2423obsolete messages. 2424 2425<DT><SAMP>‘--stringtable-output’</SAMP> 2426<DD> 2427<A NAME="IDX866"></A> 2428Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 2429Note that this file format doesn't support plural forms. 2430 2431<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 2432<DD> 2433<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 2434<DD> 2435<A NAME="IDX867"></A> 2436<A NAME="IDX868"></A> 2437Set the output page width. Long strings in the output files will be 2438split across multiple lines in order to ensure that each line's width 2439(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 2440 2441<DT><SAMP>‘--no-wrap’</SAMP> 2442<DD> 2443<A NAME="IDX869"></A> 2444Do not break long message lines. Message lines whose width exceeds the 2445output page width will not be split into several lines. Only file reference 2446lines which are wider than the output page width will be split. 2447 2448<DT><SAMP>‘-s’</SAMP> 2449<DD> 2450<DT><SAMP>‘--sort-output’</SAMP> 2451<DD> 2452<A NAME="IDX870"></A> 2453<A NAME="IDX871"></A> 2454Generate sorted output. Note that using this option makes it much harder 2455for the translator to understand each message's context. 2456 2457<DT><SAMP>‘-F’</SAMP> 2458<DD> 2459<DT><SAMP>‘--sort-by-file’</SAMP> 2460<DD> 2461<A NAME="IDX872"></A> 2462<A NAME="IDX873"></A> 2463Sort output by file location. 2464 2465</DL> 2466 2467 2468 2469<H3><A NAME="SEC144" HREF="gettext_toc.html#TOC144">9.9.5 Informative output</A></H3> 2470 2471<DL COMPACT> 2472 2473<DT><SAMP>‘-h’</SAMP> 2474<DD> 2475<DT><SAMP>‘--help’</SAMP> 2476<DD> 2477<A NAME="IDX874"></A> 2478<A NAME="IDX875"></A> 2479Display this help and exit. 2480 2481<DT><SAMP>‘-V’</SAMP> 2482<DD> 2483<DT><SAMP>‘--version’</SAMP> 2484<DD> 2485<A NAME="IDX876"></A> 2486<A NAME="IDX877"></A> 2487Output version information and exit. 2488 2489</DL> 2490 2491 2492 2493<H2><A NAME="SEC145" HREF="gettext_toc.html#TOC145">9.10 Invoking the <CODE>msgexec</CODE> Program</A></H2> 2494 2495<P> 2496<A NAME="IDX878"></A> 2497<A NAME="IDX879"></A> 2498 2499<PRE> 2500msgexec [<VAR>option</VAR>] <VAR>command</VAR> [<VAR>command-option</VAR>] 2501</PRE> 2502 2503<P> 2504<A NAME="IDX880"></A> 2505The <CODE>msgexec</CODE> program applies a command to all translations of a 2506translation catalog. 2507The <VAR>command</VAR> can be any program that reads a translation from standard 2508input. It is invoked once for each translation. Its output becomes 2509msgexec's output. <CODE>msgexec</CODE>'s return code is the maximum return code 2510across all invocations. 2511 2512</P> 2513<P> 2514<A NAME="IDX881"></A> 2515A special builtin command called <SAMP>‘0’</SAMP> outputs the translation, followed 2516by a null byte. The output of <SAMP>‘msgexec 0’</SAMP> is suitable as input for 2517<SAMP>‘xargs -0’</SAMP>. 2518 2519</P> 2520<P> 2521<A NAME="IDX882"></A> 2522<A NAME="IDX883"></A> 2523<A NAME="IDX884"></A> 2524During each <VAR>command</VAR> invocation, the environment variable 2525<CODE>MSGEXEC_MSGID</CODE> is bound to the message's msgid, and the environment 2526variable <CODE>MSGEXEC_LOCATION</CODE> is bound to the location in the PO file 2527of the message. If the message has a context, the environment variable 2528<CODE>MSGEXEC_MSGCTXT</CODE> is bound to the message's msgctxt, otherwise it is 2529unbound. 2530 2531</P> 2532<P> 2533<A NAME="IDX885"></A> 2534Note: It is your responsibility to ensure that the <VAR>command</VAR> can cope 2535with input encoded in the translation catalog's encoding. If the 2536<VAR>command</VAR> wants input in a particular encoding, you can in a first step 2537convert the translation catalog to that encoding using the <SAMP>‘msgconv’</SAMP> 2538program, before invoking <SAMP>‘msgexec’</SAMP>. If the <VAR>command</VAR> wants input 2539in the locale's encoding, but you want to avoid the locale's encoding, then 2540you can first convert the translation catalog to UTF-8 using the 2541<SAMP>‘msgconv’</SAMP> program and then make <SAMP>‘msgexec’</SAMP> work in an UTF-8 2542locale, by using the <CODE>LC_ALL</CODE> environment variable. 2543 2544</P> 2545 2546 2547<H3><A NAME="SEC146" HREF="gettext_toc.html#TOC146">9.10.1 Input file location</A></H3> 2548 2549<DL COMPACT> 2550 2551<DT><SAMP>‘-i <VAR>inputfile</VAR>’</SAMP> 2552<DD> 2553<DT><SAMP>‘--input=<VAR>inputfile</VAR>’</SAMP> 2554<DD> 2555<A NAME="IDX886"></A> 2556<A NAME="IDX887"></A> 2557Input PO file. 2558 2559<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 2560<DD> 2561<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 2562<DD> 2563<A NAME="IDX888"></A> 2564<A NAME="IDX889"></A> 2565Add <VAR>directory</VAR> to the list of directories. Source files are 2566searched relative to this list of directories. The resulting <TT>‘.po’</TT> 2567file will be written relative to the current directory, though. 2568 2569</DL> 2570 2571<P> 2572If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read. 2573 2574</P> 2575 2576 2577<H3><A NAME="SEC147" HREF="gettext_toc.html#TOC147">9.10.2 Input file syntax</A></H3> 2578 2579<DL COMPACT> 2580 2581<DT><SAMP>‘-P’</SAMP> 2582<DD> 2583<DT><SAMP>‘--properties-input’</SAMP> 2584<DD> 2585<A NAME="IDX890"></A> 2586<A NAME="IDX891"></A> 2587Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> 2588syntax, not in PO file syntax. 2589 2590<DT><SAMP>‘--stringtable-input’</SAMP> 2591<DD> 2592<A NAME="IDX892"></A> 2593Assume the input file is a NeXTstep/GNUstep localized resource file in 2594<CODE>.strings</CODE> syntax, not in PO file syntax. 2595 2596</DL> 2597 2598 2599 2600<H3><A NAME="SEC148" HREF="gettext_toc.html#TOC148">9.10.3 Informative output</A></H3> 2601 2602<DL COMPACT> 2603 2604<DT><SAMP>‘-h’</SAMP> 2605<DD> 2606<DT><SAMP>‘--help’</SAMP> 2607<DD> 2608<A NAME="IDX893"></A> 2609<A NAME="IDX894"></A> 2610Display this help and exit. 2611 2612<DT><SAMP>‘-V’</SAMP> 2613<DD> 2614<DT><SAMP>‘--version’</SAMP> 2615<DD> 2616<A NAME="IDX895"></A> 2617<A NAME="IDX896"></A> 2618Output version information and exit. 2619 2620</DL> 2621 2622 2623 2624<H2><A NAME="SEC149" HREF="gettext_toc.html#TOC149">9.11 Highlighting parts of PO files</A></H2> 2625 2626<P> 2627Translators are usually only interested in seeing the untranslated and 2628fuzzy messages of a PO file. Also, when a message is set fuzzy because 2629the msgid changed, they want to see the differences between the previous 2630msgid and the current one (especially if the msgid is long and only few 2631words in it have changed). Finally, it's always welcome to highlight the 2632different sections of a message in a PO file (comments, msgid, msgstr, etc.). 2633 2634</P> 2635<P> 2636Such highlighting is possible through the <CODE>msgcat</CODE> options 2637<SAMP>‘--color’</SAMP> and <SAMP>‘--style’</SAMP>. 2638 2639</P> 2640 2641 2642 2643<H3><A NAME="SEC150" HREF="gettext_toc.html#TOC150">9.11.1 The <CODE>--color</CODE> option</A></H3> 2644 2645<P> 2646<A NAME="IDX897"></A> 2647The <SAMP>‘--color=<VAR>when</VAR>’</SAMP> option specifies under which conditions 2648colorized output should be generated. The <VAR>when</VAR> part can be one of 2649the following: 2650 2651</P> 2652<DL COMPACT> 2653 2654<DT><CODE>always</CODE> 2655<DD> 2656<DT><CODE>yes</CODE> 2657<DD> 2658The output will be colorized. 2659 2660<DT><CODE>never</CODE> 2661<DD> 2662<DT><CODE>no</CODE> 2663<DD> 2664The output will not be colorized. 2665 2666<DT><CODE>auto</CODE> 2667<DD> 2668<DT><CODE>tty</CODE> 2669<DD> 2670The output will be colorized if the output device is a tty, i.e. when the 2671output goes directly to a text screen or terminal emulator window. 2672 2673<DT><CODE>html</CODE> 2674<DD> 2675The output will be colorized and be in HTML format. 2676</DL> 2677 2678<P> 2679<SAMP>‘--color’</SAMP> is equivalent to <SAMP>‘--color=yes’</SAMP>. The default is 2680<SAMP>‘--color=auto’</SAMP>. 2681 2682</P> 2683<P> 2684Thus, a command like <SAMP>‘msgcat vi.po’</SAMP> will produce colorized output 2685when called by itself in a command window. Whereas in a pipe, such as 2686<SAMP>‘msgcat vi.po | less -R’</SAMP>, it will not produce colorized output. To 2687get colorized output in this situation nevertheless, use the command 2688<SAMP>‘msgcat --color vi.po | less -R’</SAMP>. 2689 2690</P> 2691<P> 2692The <SAMP>‘--color=html’</SAMP> option will produce output that can be viewed in 2693a browser. This can be useful, for example, for Indic languages, 2694because the renderic of Indic scripts in browser is usually better than 2695in terminal emulators. 2696 2697</P> 2698<P> 2699Note that the output produced with the <CODE>--color</CODE> option is <EM>not</EM> 2700a valid PO file in itself. It contains additional terminal-specific escape 2701sequences or HTML tags. A PO file reader will give a syntax error when 2702confronted with such content. Except for the <SAMP>‘--color=html’</SAMP> case, 2703you therefore normally don't need to save output produced with the 2704<CODE>--color</CODE> option in a file. 2705 2706</P> 2707 2708 2709<H3><A NAME="SEC151" HREF="gettext_toc.html#TOC151">9.11.2 The environment variable <CODE>TERM</CODE></A></H3> 2710 2711<P> 2712<A NAME="IDX898"></A> 2713The environment variable <CODE>TERM</CODE> contains a identifier for the text 2714window's capabilities. You can get a detailed list of these cababilities 2715by using the <SAMP>‘infocmp’</SAMP> command, using <SAMP>‘man 5 terminfo’</SAMP> as a 2716reference. 2717 2718</P> 2719<P> 2720When producing text with embedded color directives, <CODE>msgcat</CODE> looks 2721at the <CODE>TERM</CODE> variable. Text windows today typically support at least 27228 colors. Often, however, the text window supports 16 or more colors, 2723even though the <CODE>TERM</CODE> variable is set to a identifier denoting only 27248 supported colors. It can be worth setting the <CODE>TERM</CODE> variable to 2725a different value in these cases: 2726 2727</P> 2728<DL COMPACT> 2729 2730<DT><CODE>xterm</CODE> 2731<DD> 2732<CODE>xterm</CODE> is in most cases built with support for 16 colors. It can also 2733be built with support for 88 or 256 colors (but not both). You can try to 2734set <CODE>TERM</CODE> to either <CODE>xterm-16color</CODE>, <CODE>xterm-88color</CODE>, or 2735<CODE>xterm-256color</CODE>. 2736 2737<DT><CODE>rxvt</CODE> 2738<DD> 2739<CODE>rxvt</CODE> is often built with support for 16 colors. You can try to set 2740<CODE>TERM</CODE> to <CODE>rxvt-16color</CODE>. 2741 2742<DT><CODE>konsole</CODE> 2743<DD> 2744<CODE>konsole</CODE> too is often built with support for 16 colors. You can try to 2745set <CODE>TERM</CODE> to <CODE>konsole-16color</CODE> or <CODE>xterm-16color</CODE>. 2746</DL> 2747 2748<P> 2749After setting <CODE>TERM</CODE>, you can verify it by invoking 2750<SAMP>‘msgcat --color=test’</SAMP> and seeing whether the output looks like a 2751reasonable color map. 2752 2753</P> 2754 2755 2756<H3><A NAME="SEC152" HREF="gettext_toc.html#TOC152">9.11.3 The <CODE>--style</CODE> option</A></H3> 2757 2758<P> 2759<A NAME="IDX899"></A> 2760The <SAMP>‘--style=<VAR>style_file</VAR>’</SAMP> option specifies the style file to use 2761when colorizing. It has an effect only when the <CODE>--color</CODE> option is 2762effective. 2763 2764</P> 2765<P> 2766<A NAME="IDX900"></A> 2767If the <CODE>--style</CODE> option is not specified, the environment variable 2768<CODE>PO_STYLE</CODE> is considered. It is meant to point to the user's 2769preferred style for PO files. 2770 2771</P> 2772<P> 2773The default style file is <TT>‘$prefix/share/gettext/styles/po-default.css’</TT>, 2774where <CODE>$prefix</CODE> is the installation location. 2775 2776</P> 2777<P> 2778A few style files are predefined: 2779<DL COMPACT> 2780 2781<DT><TT>‘po-vim.css’</TT> 2782<DD> 2783This style imitates the look used by vim 7. 2784 2785<DT><TT>‘po-emacs-x.css’</TT> 2786<DD> 2787This style imitates the look used by GNU Emacs 21 and 22 in an X11 window. 2788 2789<DT><TT>‘po-emacs-xterm.css’</TT> 2790<DD> 2791<DT><TT>‘po-emacs-xterm16.css’</TT> 2792<DD> 2793<DT><TT>‘po-emacs-xterm256.css’</TT> 2794<DD> 2795This style imitates the look used by GNU Emacs 22 in a terminal of type 2796<SAMP>‘xterm’</SAMP> (8 colors) or <SAMP>‘xterm-16color’</SAMP> (16 colors) or 2797<SAMP>‘xterm-256color’</SAMP> (256 colors), respectively. 2798</DL> 2799 2800<P> 2801You can use these styles without specifying a directory. They are actually 2802located in <TT>‘$prefix/share/gettext/styles/’</TT>, where <CODE>$prefix</CODE> is the 2803installation location. 2804 2805</P> 2806<P> 2807You can also design your own styles. This is described in the next section. 2808 2809</P> 2810 2811 2812 2813<H3><A NAME="SEC153" HREF="gettext_toc.html#TOC153">9.11.4 Style rules for PO files</A></H3> 2814 2815<P> 2816The same style file can be used for styling of a PO file, for terminal 2817output and for HTML output. It is written in CSS (Cascading Style Sheet) 2818syntax. See <A HREF="http://www.w3.org/TR/css2/cover.html">http://www.w3.org/TR/css2/cover.html</A> for a formal 2819definition of CSS. Many HTML authoring tutorials also contain explanations 2820of CSS. 2821 2822</P> 2823<P> 2824In the case of HTML output, the style file is embedded in the HTML output. 2825In the case of text output, the style file is interpreted by the 2826<CODE>msgcat</CODE> program. This means, in particular, that when 2827<CODE>@import</CODE> is used with relative file names, the file names are 2828 2829</P> 2830 2831<UL> 2832<LI> 2833 2834relative to the resulting HTML file, in the case of HTML output, 2835 2836<LI> 2837 2838relative to the style sheet containing the <CODE>@import</CODE>, in the case of 2839text output. (Actually, <CODE>@import</CODE>s are not yet supported in this case, 2840due to a limitation in <CODE>libcroco</CODE>.) 2841</UL> 2842 2843<P> 2844CSS rules are built up from selectors and declarations. The declarations 2845specify graphical properties; the selectors specify specify when they apply. 2846 2847</P> 2848<P> 2849In PO files, the following simple selectors (based on "CSS classes", see 2850the CSS2 spec, section 5.8.3) are supported. 2851 2852</P> 2853 2854<UL> 2855<LI> 2856 2857Selectors that apply to entire messages: 2858 2859<DL COMPACT> 2860 2861<DT><CODE>.header</CODE> 2862<DD> 2863This matches the header entry of a PO file. 2864 2865<DT><CODE>.translated</CODE> 2866<DD> 2867This matches a translated message. 2868 2869<DT><CODE>.untranslated</CODE> 2870<DD> 2871This matches an untranslated message (i.e. a message with empty translation). 2872 2873<DT><CODE>.fuzzy</CODE> 2874<DD> 2875This matches a fuzzy message (i.e. a message which has a translation that 2876needs review by the translator). 2877 2878<DT><CODE>.obsolete</CODE> 2879<DD> 2880This matches an obsolete message (i.e. a message that was translated but is 2881not needed by the current POT file any more). 2882</DL> 2883 2884<LI> 2885 2886Selectors that apply to parts of a message in PO syntax. Recall the general 2887structure of a message in PO syntax: 2888 2889 2890<PRE> 2891<VAR>white-space</VAR> 2892# <VAR>translator-comments</VAR> 2893#. <VAR>extracted-comments</VAR> 2894#: <VAR>reference</VAR>... 2895#, <VAR>flag</VAR>... 2896#| msgid <VAR>previous-untranslated-string</VAR> 2897msgid <VAR>untranslated-string</VAR> 2898msgstr <VAR>translated-string</VAR> 2899</PRE> 2900 2901<DL COMPACT> 2902 2903<DT><CODE>.comment</CODE> 2904<DD> 2905This matches all comments (translator comments, extracted comments, 2906source file reference comments, flag comments, previous message comments, 2907as well as the entire obsolete messages). 2908 2909<DT><CODE>.translator-comment</CODE> 2910<DD> 2911This matches the translator comments. 2912 2913<DT><CODE>.extracted-comment</CODE> 2914<DD> 2915This matches the extracted comments, i.e. the comments placed by the 2916programmer at the attention of the translator. 2917 2918<DT><CODE>.reference-comment</CODE> 2919<DD> 2920This matches the source file reference comments (entire lines). 2921 2922<DT><CODE>.reference</CODE> 2923<DD> 2924This matches the individual source file references inside the source file 2925reference comment lines. 2926 2927<DT><CODE>.flag-comment</CODE> 2928<DD> 2929This matches the flag comment lines (entire lines). 2930 2931<DT><CODE>.flag</CODE> 2932<DD> 2933This matches the individual flags inside flag comment lines. 2934 2935<DT><CODE>.fuzzy-flag</CODE> 2936<DD> 2937This matches the `fuzzy' flag inside flag comment lines. 2938 2939<DT><CODE>.previous-comment</CODE> 2940<DD> 2941This matches the comments containing the previous untranslated string (entire 2942lines). 2943 2944<DT><CODE>.previous</CODE> 2945<DD> 2946This matches the previous untranslated string including the string delimiters, 2947the associated keywords (<CODE>msgid</CODE> etc.) and the spaces between them. 2948 2949<DT><CODE>.msgid</CODE> 2950<DD> 2951This matches the untranslated string including the string delimiters, 2952the associated keywords (<CODE>msgid</CODE> etc.) and the spaces between them. 2953 2954<DT><CODE>.msgstr</CODE> 2955<DD> 2956This matches the translated string including the string delimiters, 2957the associated keywords (<CODE>msgstr</CODE> etc.) and the spaces between them. 2958 2959<DT><CODE>.keyword</CODE> 2960<DD> 2961This matches the keywords (<CODE>msgid</CODE>, <CODE>msgstr</CODE>, etc.). 2962 2963<DT><CODE>.string</CODE> 2964<DD> 2965This matches strings, including the string delimiters (double quotes). 2966</DL> 2967 2968<LI> 2969 2970Selectors that apply to parts of strings: 2971 2972<DL COMPACT> 2973 2974<DT><CODE>.text</CODE> 2975<DD> 2976This matches the entire contents of a string (excluding the string delimiters, 2977i.e. the double quotes). 2978 2979<DT><CODE>.escape-sequence</CODE> 2980<DD> 2981This matches an escape sequence (starting with a backslash). 2982 2983<DT><CODE>.format-directive</CODE> 2984<DD> 2985This matches a format string directive (starting with a <SAMP>‘%’</SAMP> sign in the 2986case of most programming languages, with a <SAMP>‘{’</SAMP> in the case of 2987<CODE>java-format</CODE> and <CODE>csharp-format</CODE>, with a <SAMP>‘~’</SAMP> in the case of 2988<CODE>lisp-format</CODE> and <CODE>scheme-format</CODE>, or with <SAMP>‘$’</SAMP> in the case of 2989<CODE>sh-format</CODE>). 2990 2991<DT><CODE>.invalid-format-directive</CODE> 2992<DD> 2993This matches an invalid format string directive. 2994 2995<DT><CODE>.added</CODE> 2996<DD> 2997In an untranslated string, this matches a part of the string that was not 2998present in the previous untranslated string. (Not yet implemented in this 2999release.) 3000 3001<DT><CODE>.changed</CODE> 3002<DD> 3003In an untranslated string or in a previous untranslated string, this matches 3004a part of the string that is changed or replaced. (Not yet implemented in 3005this release.) 3006 3007<DT><CODE>.removed</CODE> 3008<DD> 3009In a previous untranslated string, this matches a part of the string that 3010is not present in the current untranslated string. (Not yet implemented in 3011this release.) 3012</DL> 3013</UL> 3014 3015<P> 3016These selectors can be combined to hierarchical selectors. For example, 3017 3018</P> 3019 3020<PRE> 3021.msgstr .invalid-format-directive { color: red; } 3022</PRE> 3023 3024<P> 3025will highlight the invalid format directives in the translated strings. 3026 3027</P> 3028<P> 3029In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements 3030(CSS2 spec, section 5.12) are not supported. 3031 3032</P> 3033<P> 3034The declarations in HTML mode are not limited; any graphical attribute 3035supported by the browsers can be used. 3036 3037</P> 3038<P> 3039The declarations in text mode are limited to the following properties. Other 3040properties will be silently ignored. 3041 3042</P> 3043<DL COMPACT> 3044 3045<DT><CODE>color</CODE> (CSS2 spec, section 14.1) 3046<DD> 3047<DT><CODE>background-color</CODE> (CSS2 spec, section 14.2.1) 3048<DD> 3049These properties is supported. Colors will be adjusted to match the terminal's 3050capabilities. Note that many terminals support only 8 colors. 3051 3052<DT><CODE>font-weight</CODE> (CSS2 spec, section 15.2.3) 3053<DD> 3054This property is supported, but most terminals can only render two different 3055weights: <CODE>normal</CODE> and <CODE>bold</CODE>. Values >= 600 are rendered as 3056<CODE>bold</CODE>. 3057 3058<DT><CODE>font-style</CODE> (CSS2 spec, section 15.2.3) 3059<DD> 3060This property is supported. The values <CODE>italic</CODE> and <CODE>oblique</CODE> are 3061rendered the same way. 3062 3063<DT><CODE>text-decoration</CODE> (CSS2 spec, section 16.3.1) 3064<DD> 3065This property is supported, limited to the values <CODE>none</CODE> and 3066<CODE>underline</CODE>. 3067</DL> 3068 3069 3070 3071<H3><A NAME="SEC154" HREF="gettext_toc.html#TOC154">9.11.5 Customizing <CODE>less</CODE> for viewing PO files</A></H3> 3072 3073<P> 3074The <SAMP>‘less’</SAMP> program is a popular text file browser for use in a text 3075screen or terminal emulator. It also supports text with embedded escape 3076sequences for colors and text decorations. 3077 3078</P> 3079<P> 3080You can use <CODE>less</CODE> to view a PO file like this (assuming an UTF-8 3081environment): 3082 3083</P> 3084 3085<PRE> 3086msgcat --to-code=UTF-8 --color xyz.po | less -R 3087</PRE> 3088 3089<P> 3090You can simplify this to this simple command: 3091 3092</P> 3093 3094<PRE> 3095less xyz.po 3096</PRE> 3097 3098<P> 3099after these three preparations: 3100 3101</P> 3102 3103<OL> 3104<LI> 3105 3106Add the options <SAMP>‘-R’</SAMP> and <SAMP>‘-f’</SAMP> to the <CODE>LESS</CODE> environment 3107variable. In sh shells: 3108 3109<PRE> 3110$ LESS="$LESS -R -f" 3111$ export LESS 3112</PRE> 3113 3114<LI> 3115 3116If your system does not already have the <TT>‘lessopen.sh’</TT> and 3117<TT>‘lessclose.sh’</TT> scripts, create them and set the <CODE>LESSOPEN</CODE> and 3118<CODE>LESSCLOSE</CODE> environment variables, as indicated in the manual page 3119(<SAMP>‘man less’</SAMP>). 3120 3121<LI> 3122 3123Add to <TT>‘lessopen.sh’</TT> a piece of script that recognizes PO files 3124through their file extension and invokes <CODE>msgcat</CODE> on them, producing 3125a temporary file. Like this: 3126 3127 3128<PRE> 3129case "$1" in 3130 *.po) 3131 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"` 3132 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile" 3133 echo "$tmpfile" 3134 exit 0 3135 ;; 3136esac 3137</PRE> 3138 3139</OL> 3140 3141 3142 3143<H2><A NAME="SEC155" HREF="gettext_toc.html#TOC155">9.12 Writing your own programs that process PO files</A></H2> 3144 3145<P> 3146For the tasks for which a combination of <SAMP>‘msgattrib’</SAMP>, <SAMP>‘msgcat’</SAMP> etc. 3147is not sufficient, a set of C functions is provided in a library, to make it 3148possible to process PO files in your own programs. When you use this library, 3149you don't need to write routines to parse the PO file; instead, you retrieve 3150a pointer in memory to each of messages contained in the PO file. Functions 3151for writing PO files are not provided at this time. 3152 3153</P> 3154<P> 3155The functions are declared in the header file <SAMP>‘<gettext-po.h>’</SAMP>, and are 3156defined in a library called <SAMP>‘libgettextpo’</SAMP>. 3157 3158</P> 3159<P> 3160<DL> 3161<DT><U>Data Type:</U> <B>po_file_t</B> 3162<DD><A NAME="IDX901"></A> 3163This is a pointer type that refers to the contents of a PO file, after it has 3164been read into memory. 3165</DL> 3166 3167</P> 3168<P> 3169<DL> 3170<DT><U>Data Type:</U> <B>po_message_iterator_t</B> 3171<DD><A NAME="IDX902"></A> 3172This is a pointer type that refers to an iterator that produces a sequence of 3173messages. 3174</DL> 3175 3176</P> 3177<P> 3178<DL> 3179<DT><U>Data Type:</U> <B>po_message_t</B> 3180<DD><A NAME="IDX903"></A> 3181This is a pointer type that refers to a message of a PO file, including its 3182translation. 3183</DL> 3184 3185</P> 3186<P> 3187<DL> 3188<DT><U>Function:</U> po_file_t <B>po_file_read</B> <I>(const char *<VAR>filename</VAR>)</I> 3189<DD><A NAME="IDX904"></A> 3190The <CODE>po_file_read</CODE> function reads a PO file into memory. The file name 3191is given as argument. The return value is a handle to the PO file's contents, 3192valid until <CODE>po_file_free</CODE> is called on it. In case of error, the return 3193value is <CODE>NULL</CODE>, and <CODE>errno</CODE> is set. 3194</DL> 3195 3196</P> 3197<P> 3198<DL> 3199<DT><U>Function:</U> void <B>po_file_free</B> <I>(po_file_t <VAR>file</VAR>)</I> 3200<DD><A NAME="IDX905"></A> 3201The <CODE>po_file_free</CODE> function frees a PO file's contents from memory, 3202including all messages that are only implicitly accessible through iterators. 3203</DL> 3204 3205</P> 3206<P> 3207<DL> 3208<DT><U>Function:</U> const char * const * <B>po_file_domains</B> <I>(po_file_t <VAR>file</VAR>)</I> 3209<DD><A NAME="IDX906"></A> 3210The <CODE>po_file_domains</CODE> function returns the domains for which the given 3211PO file has messages. The return value is a <CODE>NULL</CODE> terminated array 3212which is valid as long as the <VAR>file</VAR> handle is valid. For PO files which 3213contain no <SAMP>‘domain’</SAMP> directive, the return value contains only one domain, 3214namely the default domain <CODE>"messages"</CODE>. 3215</DL> 3216 3217</P> 3218<P> 3219<DL> 3220<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> 3221<DD><A NAME="IDX907"></A> 3222The <CODE>po_message_iterator</CODE> returns an iterator that will produce the 3223messages of <VAR>file</VAR> that belong to the given <VAR>domain</VAR>. If <VAR>domain</VAR> 3224is <CODE>NULL</CODE>, the default domain is used instead. To list the messages, 3225use the function <CODE>po_next_message</CODE> repeatedly. 3226</DL> 3227 3228</P> 3229<P> 3230<DL> 3231<DT><U>Function:</U> void <B>po_message_iterator_free</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I> 3232<DD><A NAME="IDX908"></A> 3233The <CODE>po_message_iterator_free</CODE> function frees an iterator previously 3234allocated through the <CODE>po_message_iterator</CODE> function. 3235</DL> 3236 3237</P> 3238<P> 3239<DL> 3240<DT><U>Function:</U> po_message_t <B>po_next_message</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I> 3241<DD><A NAME="IDX909"></A> 3242The <CODE>po_next_message</CODE> function returns the next message from 3243<VAR>iterator</VAR> and advances the iterator. It returns <CODE>NULL</CODE> when the 3244iterator has reached the end of its message list. 3245</DL> 3246 3247</P> 3248<P> 3249The following functions returns details of a <CODE>po_message_t</CODE>. Recall 3250that the results are valid as long as the <VAR>file</VAR> handle is valid. 3251 3252</P> 3253<P> 3254<DL> 3255<DT><U>Function:</U> const char * <B>po_message_msgid</B> <I>(po_message_t <VAR>message</VAR>)</I> 3256<DD><A NAME="IDX910"></A> 3257The <CODE>po_message_msgid</CODE> function returns the <CODE>msgid</CODE> (untranslated 3258English string) of a message. This is guaranteed to be non-<CODE>NULL</CODE>. 3259</DL> 3260 3261</P> 3262<P> 3263<DL> 3264<DT><U>Function:</U> const char * <B>po_message_msgid_plural</B> <I>(po_message_t <VAR>message</VAR>)</I> 3265<DD><A NAME="IDX911"></A> 3266The <CODE>po_message_msgid_plural</CODE> function returns the <CODE>msgid_plural</CODE> 3267(untranslated English plural string) of a message with plurals, or <CODE>NULL</CODE> 3268for a message without plural. 3269</DL> 3270 3271</P> 3272<P> 3273<DL> 3274<DT><U>Function:</U> const char * <B>po_message_msgstr</B> <I>(po_message_t <VAR>message</VAR>)</I> 3275<DD><A NAME="IDX912"></A> 3276The <CODE>po_message_msgstr</CODE> function returns the <CODE>msgstr</CODE> (translation) 3277of a message. For an untranslated message, the return value is an empty 3278string. 3279</DL> 3280 3281</P> 3282<P> 3283<DL> 3284<DT><U>Function:</U> const char * <B>po_message_msgstr_plural</B> <I>(po_message_t <VAR>message</VAR>, int <VAR>index</VAR>)</I> 3285<DD><A NAME="IDX913"></A> 3286The <CODE>po_message_msgstr_plural</CODE> function returns the 3287<CODE>msgstr[<VAR>index</VAR>]</CODE> of a message with plurals, or <CODE>NULL</CODE> when 3288the <VAR>index</VAR> is out of range or for a message without plural. 3289</DL> 3290 3291</P> 3292<P> 3293Here is an example code how these functions can be used. 3294 3295</P> 3296 3297<PRE> 3298const char *filename = ...; 3299po_file_t file = po_file_read (filename); 3300 3301if (file == NULL) 3302 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename); 3303{ 3304 const char * const *domains = po_file_domains (file); 3305 const char * const *domainp; 3306 3307 for (domainp = domains; *domainp; domainp++) 3308 { 3309 const char *domain = *domainp; 3310 po_message_iterator_t iterator = po_message_iterator (file, domain); 3311 3312 for (;;) 3313 { 3314 po_message_t *message = po_next_message (iterator); 3315 3316 if (message == NULL) 3317 break; 3318 { 3319 const char *msgid = po_message_msgid (message); 3320 const char *msgstr = po_message_msgstr (message); 3321 3322 ... 3323 } 3324 } 3325 po_message_iterator_free (iterator); 3326 } 3327} 3328po_file_free (file); 3329</PRE> 3330 3331<P><HR><P> 3332Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_8.html">previous</A>, <A HREF="gettext_10.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. 3333</BODY> 3334</HTML> 3335