3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 11 June 2016 -->
6 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
7 <TITLE>GNU gettext utilities - 9 Manipulating PO Files</TITLE>
10 Go 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>.
14 <H1><A NAME="SEC79" HREF="gettext_toc.html#TOC79">9 Manipulating PO Files</A></H1>
20 Sometimes it is necessary to manipulate PO files in a way that is better
21 performed automatically than by hand. GNU <CODE>gettext</CODE> includes a
22 complete set of tools for this purpose.
27 When merging two packages into a single package, the resulting POT file
28 will be the concatenation of the two packages' POT files. Thus the
29 maintainer must concatenate the two existing package translations into
30 a single translation catalog, for each language. This is best performed
31 using <SAMP>‘msgcat’</SAMP>. It is then the translators' duty to deal with any
32 possible conflicts that arose during the merge.
37 When a translator takes over the translation job from another translator,
38 but she uses a different character encoding in her locale, she will
39 convert the catalog to her character encoding. This is best done through
40 the <SAMP>‘msgconv’</SAMP> program.
44 When a maintainer takes a source file with tagged messages from another
45 package, he should also take the existing translations for this source
46 file (and not let the translators do the same job twice). One way to do
47 this is through <SAMP>‘msggrep’</SAMP>, another is to create a POT file for
48 that source file and use <SAMP>‘msgmerge’</SAMP>.
54 When a translator wants to adjust some translation catalog for a special
55 dialect or orthography -- for example, German as written in Switzerland
56 versus German as written in Germany -- she needs to apply some text
57 processing to every message in the catalog. The tool for doing this is
58 <SAMP>‘msgfilter’</SAMP>.
62 Another use of <CODE>msgfilter</CODE> is to produce approximately the POT file for
63 which a given PO file was made. This can be done through a filter command
64 like <SAMP>‘msgfilter sed -e d | sed -e '/^# /d'’</SAMP>. Note that the original
65 POT file may have had different comments and different plural message counts,
66 that's why it's better to use the original POT file if available.
71 When a translator wants to check her translations, for example according
72 to orthography rules or using a non-interactive spell checker, she can do
73 so using the <SAMP>‘msgexec’</SAMP> program.
78 When third party tools create PO or POT files, sometimes duplicates cannot
79 be avoided. But the GNU <CODE>gettext</CODE> tools give an error when they
80 encounter duplicate msgids in the same file and in the same domain.
81 To merge duplicates, the <SAMP>‘msguniq’</SAMP> program can be used.
85 <SAMP>‘msgcomm’</SAMP> is a more general tool for keeping or throwing away
86 duplicates, occurring in different files.
90 <SAMP>‘msgcmp’</SAMP> can be used to check whether a translation catalog is
91 completely translated.
96 <SAMP>‘msgattrib’</SAMP> can be used to select and extract only the fuzzy
97 or untranslated messages of a translation catalog.
101 <SAMP>‘msgen’</SAMP> is useful as a first step for preparing English translation
102 catalogs. It copies each message's msgid to its msgstr.
106 Finally, for those applications where all these various programs are not
107 sufficient, a library <SAMP>‘libgettextpo’</SAMP> is provided that can be used to
108 write other specialized programs that process PO files.
114 <H2><A NAME="SEC80" HREF="gettext_toc.html#TOC80">9.1 Invoking the <CODE>msgcat</CODE> Program</A></H2>
117 <A NAME="IDX554"></A>
118 <A NAME="IDX555"></A>
121 msgcat [<VAR>option</VAR>] [<VAR>inputfile</VAR>]...
125 <A NAME="IDX556"></A>
126 <A NAME="IDX557"></A>
127 The <CODE>msgcat</CODE> program concatenates and merges the specified PO files.
128 It finds messages which are common to two or more of the specified PO files.
129 By using the <CODE>--more-than</CODE> option, greater commonality may be requested
130 before messages are printed. Conversely, the <CODE>--less-than</CODE> option may be
131 used to specify less commonality before messages are printed (i.e.
132 <SAMP>‘--less-than=2’</SAMP> will only print the unique messages). Translations,
133 comments, extracted comments, and file positions will be cumulated, except that
134 if <CODE>--use-first</CODE> is specified, they will be taken from the first PO file
140 <H3><A NAME="SEC81" HREF="gettext_toc.html#TOC81">9.1.1 Input file location</A></H3>
144 <DT><SAMP>‘<VAR>inputfile</VAR> ...’</SAMP>
148 <DT><SAMP>‘-f <VAR>file</VAR>’</SAMP>
150 <DT><SAMP>‘--files-from=<VAR>file</VAR>’</SAMP>
152 <A NAME="IDX558"></A>
153 <A NAME="IDX559"></A>
154 Read the names of the input files from <VAR>file</VAR> instead of getting
155 them from the command line.
157 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
159 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
161 <A NAME="IDX560"></A>
162 <A NAME="IDX561"></A>
163 Add <VAR>directory</VAR> to the list of directories. Source files are
164 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
165 file will be written relative to the current directory, though.
170 If <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read.
175 <H3><A NAME="SEC82" HREF="gettext_toc.html#TOC82">9.1.2 Output file location</A></H3>
179 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
181 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
183 <A NAME="IDX562"></A>
184 <A NAME="IDX563"></A>
185 Write output to specified file.
190 <A NAME="IDX564"></A>
191 The results are written to standard output if no output file is specified
192 or if it is <SAMP>‘-’</SAMP>.
197 <H3><A NAME="SEC83" HREF="gettext_toc.html#TOC83">9.1.3 Message selection</A></H3>
201 <DT><SAMP>‘-< <VAR>number</VAR>’</SAMP>
203 <DT><SAMP>‘--less-than=<VAR>number</VAR>’</SAMP>
205 <A NAME="IDX565"></A>
206 <A NAME="IDX566"></A>
207 Print messages with less than <VAR>number</VAR> definitions, defaults to infinite
210 <DT><SAMP>‘-> <VAR>number</VAR>’</SAMP>
212 <DT><SAMP>‘--more-than=<VAR>number</VAR>’</SAMP>
214 <A NAME="IDX567"></A>
215 <A NAME="IDX568"></A>
216 Print messages with more than <VAR>number</VAR> definitions, defaults to 0 if not
219 <DT><SAMP>‘-u’</SAMP>
221 <DT><SAMP>‘--unique’</SAMP>
223 <A NAME="IDX569"></A>
224 <A NAME="IDX570"></A>
225 Shorthand for <SAMP>‘--less-than=2’</SAMP>. Requests that only unique messages be
232 <H3><A NAME="SEC84" HREF="gettext_toc.html#TOC84">9.1.4 Input file syntax</A></H3>
236 <DT><SAMP>‘-P’</SAMP>
238 <DT><SAMP>‘--properties-input’</SAMP>
240 <A NAME="IDX571"></A>
241 <A NAME="IDX572"></A>
242 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
243 syntax, not in PO file syntax.
245 <DT><SAMP>‘--stringtable-input’</SAMP>
247 <A NAME="IDX573"></A>
248 Assume the input files are NeXTstep/GNUstep localized resource files in
249 <CODE>.strings</CODE> syntax, not in PO file syntax.
255 <H3><A NAME="SEC85" HREF="gettext_toc.html#TOC85">9.1.5 Output details</A></H3>
259 <DT><SAMP>‘-t’</SAMP>
261 <DT><SAMP>‘--to-code=<VAR>name</VAR>’</SAMP>
263 <A NAME="IDX574"></A>
264 <A NAME="IDX575"></A>
265 Specify encoding for output.
267 <DT><SAMP>‘--use-first’</SAMP>
269 <A NAME="IDX576"></A>
270 Use first available translation for each message. Don't merge several
271 translations into one.
273 <DT><SAMP>‘--lang=<VAR>catalogname</VAR>’</SAMP>
275 <A NAME="IDX577"></A>
276 Specify the <SAMP>‘Language’</SAMP> field to be used in the header entry. See
277 section <A HREF="gettext_6.html#SEC44">6.2 Filling in the Header Entry</A> for the meaning of this field. Note: The
278 <SAMP>‘Language-Team’</SAMP> and <SAMP>‘Plural-Forms’</SAMP> fields are left unchanged.
280 <DT><SAMP>‘--color’</SAMP>
282 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
284 <A NAME="IDX578"></A>
285 Specify whether or when to use colors and other text attributes.
286 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
288 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
290 <A NAME="IDX579"></A>
291 Specify the CSS style rule file to use for <CODE>--color</CODE>.
292 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
294 <DT><SAMP>‘--force-po’</SAMP>
296 <A NAME="IDX580"></A>
297 Always write an output file even if it contains no message.
299 <DT><SAMP>‘-i’</SAMP>
301 <DT><SAMP>‘--indent’</SAMP>
303 <A NAME="IDX581"></A>
304 <A NAME="IDX582"></A>
305 Write the .po file using indented style.
307 <DT><SAMP>‘--no-location’</SAMP>
309 <A NAME="IDX583"></A>
310 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
312 <DT><SAMP>‘-n’</SAMP>
314 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
316 <A NAME="IDX584"></A>
317 <A NAME="IDX585"></A>
318 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
320 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
321 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
322 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
323 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
324 suppresses the lines (same as <CODE>--no-location</CODE>).
326 <DT><SAMP>‘--strict’</SAMP>
328 <A NAME="IDX586"></A>
329 Write out a strict Uniforum conforming PO file. Note that this
330 Uniforum format should be avoided because it doesn't support the
333 <DT><SAMP>‘-p’</SAMP>
335 <DT><SAMP>‘--properties-output’</SAMP>
337 <A NAME="IDX587"></A>
338 <A NAME="IDX588"></A>
339 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
340 that this file format doesn't support plural forms and silently drops
343 <DT><SAMP>‘--stringtable-output’</SAMP>
345 <A NAME="IDX589"></A>
346 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
347 Note that this file format doesn't support plural forms.
349 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
351 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
353 <A NAME="IDX590"></A>
354 <A NAME="IDX591"></A>
355 Set the output page width. Long strings in the output files will be
356 split across multiple lines in order to ensure that each line's width
357 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
359 <DT><SAMP>‘--no-wrap’</SAMP>
361 <A NAME="IDX592"></A>
362 Do not break long message lines. Message lines whose width exceeds the
363 output page width will not be split into several lines. Only file reference
364 lines which are wider than the output page width will be split.
366 <DT><SAMP>‘-s’</SAMP>
368 <DT><SAMP>‘--sort-output’</SAMP>
370 <A NAME="IDX593"></A>
371 <A NAME="IDX594"></A>
372 <A NAME="IDX595"></A>
373 Generate sorted output. Note that using this option makes it much harder
374 for the translator to understand each message's context.
376 <DT><SAMP>‘-F’</SAMP>
378 <DT><SAMP>‘--sort-by-file’</SAMP>
380 <A NAME="IDX596"></A>
381 <A NAME="IDX597"></A>
382 Sort output by file location.
388 <H3><A NAME="SEC86" HREF="gettext_toc.html#TOC86">9.1.6 Informative output</A></H3>
392 <DT><SAMP>‘-h’</SAMP>
394 <DT><SAMP>‘--help’</SAMP>
396 <A NAME="IDX598"></A>
397 <A NAME="IDX599"></A>
398 Display this help and exit.
400 <DT><SAMP>‘-V’</SAMP>
402 <DT><SAMP>‘--version’</SAMP>
404 <A NAME="IDX600"></A>
405 <A NAME="IDX601"></A>
406 Output version information and exit.
412 <H2><A NAME="SEC87" HREF="gettext_toc.html#TOC87">9.2 Invoking the <CODE>msgconv</CODE> Program</A></H2>
415 <A NAME="IDX602"></A>
416 <A NAME="IDX603"></A>
419 msgconv [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
423 <A NAME="IDX604"></A>
424 The <CODE>msgconv</CODE> program converts a translation catalog to a different
430 <H3><A NAME="SEC88" HREF="gettext_toc.html#TOC88">9.2.1 Input file location</A></H3>
434 <DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP>
438 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
440 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
442 <A NAME="IDX605"></A>
443 <A NAME="IDX606"></A>
444 Add <VAR>directory</VAR> to the list of directories. Source files are
445 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
446 file will be written relative to the current directory, though.
451 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
456 <H3><A NAME="SEC89" HREF="gettext_toc.html#TOC89">9.2.2 Output file location</A></H3>
460 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
462 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
464 <A NAME="IDX607"></A>
465 <A NAME="IDX608"></A>
466 Write output to specified file.
471 The results are written to standard output if no output file is specified
472 or if it is <SAMP>‘-’</SAMP>.
477 <H3><A NAME="SEC90" HREF="gettext_toc.html#TOC90">9.2.3 Conversion target</A></H3>
481 <DT><SAMP>‘-t’</SAMP>
483 <DT><SAMP>‘--to-code=<VAR>name</VAR>’</SAMP>
485 <A NAME="IDX609"></A>
486 <A NAME="IDX610"></A>
487 Specify encoding for output.
492 The default encoding is the current locale's encoding.
497 <H3><A NAME="SEC91" HREF="gettext_toc.html#TOC91">9.2.4 Input file syntax</A></H3>
501 <DT><SAMP>‘-P’</SAMP>
503 <DT><SAMP>‘--properties-input’</SAMP>
505 <A NAME="IDX611"></A>
506 <A NAME="IDX612"></A>
507 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
508 syntax, not in PO file syntax.
510 <DT><SAMP>‘--stringtable-input’</SAMP>
512 <A NAME="IDX613"></A>
513 Assume the input file is a NeXTstep/GNUstep localized resource file in
514 <CODE>.strings</CODE> syntax, not in PO file syntax.
520 <H3><A NAME="SEC92" HREF="gettext_toc.html#TOC92">9.2.5 Output details</A></H3>
524 <DT><SAMP>‘--color’</SAMP>
526 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
528 <A NAME="IDX614"></A>
529 Specify whether or when to use colors and other text attributes.
530 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
532 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
534 <A NAME="IDX615"></A>
535 Specify the CSS style rule file to use for <CODE>--color</CODE>.
536 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
538 <DT><SAMP>‘--force-po’</SAMP>
540 <A NAME="IDX616"></A>
541 Always write an output file even if it contains no message.
543 <DT><SAMP>‘-i’</SAMP>
545 <DT><SAMP>‘--indent’</SAMP>
547 <A NAME="IDX617"></A>
548 <A NAME="IDX618"></A>
549 Write the .po file using indented style.
551 <DT><SAMP>‘--no-location’</SAMP>
553 <A NAME="IDX619"></A>
554 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
556 <DT><SAMP>‘-n’</SAMP>
558 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
560 <A NAME="IDX620"></A>
561 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
563 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
564 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
565 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
566 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
567 suppresses the lines (same as <CODE>--no-location</CODE>).
569 <DT><SAMP>‘--strict’</SAMP>
571 <A NAME="IDX621"></A>
572 Write out a strict Uniforum conforming PO file. Note that this
573 Uniforum format should be avoided because it doesn't support the
576 <DT><SAMP>‘-p’</SAMP>
578 <DT><SAMP>‘--properties-output’</SAMP>
580 <A NAME="IDX622"></A>
581 <A NAME="IDX623"></A>
582 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
583 that this file format doesn't support plural forms and silently drops
586 <DT><SAMP>‘--stringtable-output’</SAMP>
588 <A NAME="IDX624"></A>
589 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
590 Note that this file format doesn't support plural forms.
592 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
594 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
596 <A NAME="IDX625"></A>
597 <A NAME="IDX626"></A>
598 Set the output page width. Long strings in the output files will be
599 split across multiple lines in order to ensure that each line's width
600 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
602 <DT><SAMP>‘--no-wrap’</SAMP>
604 <A NAME="IDX627"></A>
605 Do not break long message lines. Message lines whose width exceeds the
606 output page width will not be split into several lines. Only file reference
607 lines which are wider than the output page width will be split.
609 <DT><SAMP>‘-s’</SAMP>
611 <DT><SAMP>‘--sort-output’</SAMP>
613 <A NAME="IDX628"></A>
614 <A NAME="IDX629"></A>
615 Generate sorted output. Note that using this option makes it much harder
616 for the translator to understand each message's context.
618 <DT><SAMP>‘-F’</SAMP>
620 <DT><SAMP>‘--sort-by-file’</SAMP>
622 <A NAME="IDX630"></A>
623 <A NAME="IDX631"></A>
624 Sort output by file location.
630 <H3><A NAME="SEC93" HREF="gettext_toc.html#TOC93">9.2.6 Informative output</A></H3>
634 <DT><SAMP>‘-h’</SAMP>
636 <DT><SAMP>‘--help’</SAMP>
638 <A NAME="IDX632"></A>
639 <A NAME="IDX633"></A>
640 Display this help and exit.
642 <DT><SAMP>‘-V’</SAMP>
644 <DT><SAMP>‘--version’</SAMP>
646 <A NAME="IDX634"></A>
647 <A NAME="IDX635"></A>
648 Output version information and exit.
654 <H2><A NAME="SEC94" HREF="gettext_toc.html#TOC94">9.3 Invoking the <CODE>msggrep</CODE> Program</A></H2>
657 <A NAME="IDX636"></A>
658 <A NAME="IDX637"></A>
661 msggrep [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
665 <A NAME="IDX638"></A>
666 The <CODE>msggrep</CODE> program extracts all messages of a translation catalog
667 that match a given pattern or belong to some given source files.
672 <H3><A NAME="SEC95" HREF="gettext_toc.html#TOC95">9.3.1 Input file location</A></H3>
676 <DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP>
680 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
682 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
684 <A NAME="IDX639"></A>
685 <A NAME="IDX640"></A>
686 Add <VAR>directory</VAR> to the list of directories. Source files are
687 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
688 file will be written relative to the current directory, though.
693 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
698 <H3><A NAME="SEC96" HREF="gettext_toc.html#TOC96">9.3.2 Output file location</A></H3>
702 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
704 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
706 <A NAME="IDX641"></A>
707 <A NAME="IDX642"></A>
708 Write output to specified file.
713 The results are written to standard output if no output file is specified
714 or if it is <SAMP>‘-’</SAMP>.
719 <H3><A NAME="SEC97" HREF="gettext_toc.html#TOC97">9.3.3 Message selection</A></H3>
723 [-N <VAR>sourcefile</VAR>]... [-M <VAR>domainname</VAR>]...
724 [-J <VAR>msgctxt-pattern</VAR>] [-K <VAR>msgid-pattern</VAR>] [-T <VAR>msgstr-pattern</VAR>]
725 [-C <VAR>comment-pattern</VAR>]
729 A message is selected if
732 <LI>it comes from one of the specified source files,
734 <LI>or if it comes from one of the specified domains,
736 <LI>or if <SAMP>‘-J’</SAMP> is given and its context (msgctxt) matches
738 <VAR>msgctxt-pattern</VAR>,
739 <LI>or if <SAMP>‘-K’</SAMP> is given and its key (msgid or msgid_plural) matches
741 <VAR>msgid-pattern</VAR>,
742 <LI>or if <SAMP>‘-T’</SAMP> is given and its translation (msgstr) matches
744 <VAR>msgstr-pattern</VAR>,
745 <LI>or if <SAMP>‘-C’</SAMP> is given and the translator's comment matches
747 <VAR>comment-pattern</VAR>.
751 When more than one selection criterion is specified, the set of selected
752 messages is the union of the selected messages of each criterion.
756 <VAR>msgctxt-pattern</VAR> or <VAR>msgid-pattern</VAR> or <VAR>msgstr-pattern</VAR> syntax:
759 [-E | -F] [-e <VAR>pattern</VAR> | -f <VAR>file</VAR>]...
763 <VAR>pattern</VAR>s are basic regular expressions by default, or extended regular
764 expressions if -E is given, or fixed strings if -F is given.
769 <DT><SAMP>‘-N <VAR>sourcefile</VAR>’</SAMP>
771 <DT><SAMP>‘--location=<VAR>sourcefile</VAR>’</SAMP>
773 <A NAME="IDX643"></A>
774 <A NAME="IDX644"></A>
775 Select messages extracted from <VAR>sourcefile</VAR>. <VAR>sourcefile</VAR> can be
776 either a literal file name or a wildcard pattern.
778 <DT><SAMP>‘-M <VAR>domainname</VAR>’</SAMP>
780 <DT><SAMP>‘--domain=<VAR>domainname</VAR>’</SAMP>
782 <A NAME="IDX645"></A>
783 <A NAME="IDX646"></A>
784 Select messages belonging to domain <VAR>domainname</VAR>.
786 <DT><SAMP>‘-J’</SAMP>
788 <DT><SAMP>‘--msgctxt’</SAMP>
790 <A NAME="IDX647"></A>
791 <A NAME="IDX648"></A>
792 Start of patterns for the msgctxt.
794 <DT><SAMP>‘-K’</SAMP>
796 <DT><SAMP>‘--msgid’</SAMP>
798 <A NAME="IDX649"></A>
799 <A NAME="IDX650"></A>
800 Start of patterns for the msgid.
802 <DT><SAMP>‘-T’</SAMP>
804 <DT><SAMP>‘--msgstr’</SAMP>
806 <A NAME="IDX651"></A>
807 <A NAME="IDX652"></A>
808 Start of patterns for the msgstr.
810 <DT><SAMP>‘-C’</SAMP>
812 <DT><SAMP>‘--comment’</SAMP>
814 <A NAME="IDX653"></A>
815 <A NAME="IDX654"></A>
816 Start of patterns for the translator's comment.
818 <DT><SAMP>‘-X’</SAMP>
820 <DT><SAMP>‘--extracted-comment’</SAMP>
822 <A NAME="IDX655"></A>
823 <A NAME="IDX656"></A>
824 Start of patterns for the extracted comments.
826 <DT><SAMP>‘-E’</SAMP>
828 <DT><SAMP>‘--extended-regexp’</SAMP>
830 <A NAME="IDX657"></A>
831 <A NAME="IDX658"></A>
832 Specify that <VAR>pattern</VAR> is an extended regular expression.
834 <DT><SAMP>‘-F’</SAMP>
836 <DT><SAMP>‘--fixed-strings’</SAMP>
838 <A NAME="IDX659"></A>
839 <A NAME="IDX660"></A>
840 Specify that <VAR>pattern</VAR> is a set of newline-separated strings.
842 <DT><SAMP>‘-e <VAR>pattern</VAR>’</SAMP>
844 <DT><SAMP>‘--regexp=<VAR>pattern</VAR>’</SAMP>
846 <A NAME="IDX661"></A>
847 <A NAME="IDX662"></A>
848 Use <VAR>pattern</VAR> as a regular expression.
850 <DT><SAMP>‘-f <VAR>file</VAR>’</SAMP>
852 <DT><SAMP>‘--file=<VAR>file</VAR>’</SAMP>
854 <A NAME="IDX663"></A>
855 <A NAME="IDX664"></A>
856 Obtain <VAR>pattern</VAR> from <VAR>file</VAR>.
858 <DT><SAMP>‘-i’</SAMP>
860 <DT><SAMP>‘--ignore-case’</SAMP>
862 <A NAME="IDX665"></A>
863 <A NAME="IDX666"></A>
864 Ignore case distinctions.
866 <DT><SAMP>‘-v’</SAMP>
868 <DT><SAMP>‘--invert-match’</SAMP>
870 <A NAME="IDX667"></A>
871 <A NAME="IDX668"></A>
872 Output only the messages that do not match any selection criterion, instead
873 of the messages that match a selection criterion.
879 <H3><A NAME="SEC98" HREF="gettext_toc.html#TOC98">9.3.4 Input file syntax</A></H3>
883 <DT><SAMP>‘-P’</SAMP>
885 <DT><SAMP>‘--properties-input’</SAMP>
887 <A NAME="IDX669"></A>
888 <A NAME="IDX670"></A>
889 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
890 syntax, not in PO file syntax.
892 <DT><SAMP>‘--stringtable-input’</SAMP>
894 <A NAME="IDX671"></A>
895 Assume the input file is a NeXTstep/GNUstep localized resource file in
896 <CODE>.strings</CODE> syntax, not in PO file syntax.
902 <H3><A NAME="SEC99" HREF="gettext_toc.html#TOC99">9.3.5 Output details</A></H3>
906 <DT><SAMP>‘--color’</SAMP>
908 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
910 <A NAME="IDX672"></A>
911 Specify whether or when to use colors and other text attributes.
912 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
914 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
916 <A NAME="IDX673"></A>
917 Specify the CSS style rule file to use for <CODE>--color</CODE>.
918 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
920 <DT><SAMP>‘--force-po’</SAMP>
922 <A NAME="IDX674"></A>
923 Always write an output file even if it contains no message.
925 <DT><SAMP>‘--indent’</SAMP>
927 <A NAME="IDX675"></A>
928 Write the .po file using indented style.
930 <DT><SAMP>‘--no-location’</SAMP>
932 <A NAME="IDX676"></A>
933 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
935 <DT><SAMP>‘-n’</SAMP>
937 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
939 <A NAME="IDX677"></A>
940 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
942 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
943 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
944 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
945 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
946 suppresses the lines (same as <CODE>--no-location</CODE>).
948 <DT><SAMP>‘--strict’</SAMP>
950 <A NAME="IDX678"></A>
951 Write out a strict Uniforum conforming PO file. Note that this
952 Uniforum format should be avoided because it doesn't support the
955 <DT><SAMP>‘-p’</SAMP>
957 <DT><SAMP>‘--properties-output’</SAMP>
959 <A NAME="IDX679"></A>
960 <A NAME="IDX680"></A>
961 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
962 that this file format doesn't support plural forms and silently drops
965 <DT><SAMP>‘--stringtable-output’</SAMP>
967 <A NAME="IDX681"></A>
968 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
969 Note that this file format doesn't support plural forms.
971 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
973 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
975 <A NAME="IDX682"></A>
976 <A NAME="IDX683"></A>
977 Set the output page width. Long strings in the output files will be
978 split across multiple lines in order to ensure that each line's width
979 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
981 <DT><SAMP>‘--no-wrap’</SAMP>
983 <A NAME="IDX684"></A>
984 Do not break long message lines. Message lines whose width exceeds the
985 output page width will not be split into several lines. Only file reference
986 lines which are wider than the output page width will be split.
988 <DT><SAMP>‘--sort-output’</SAMP>
990 <A NAME="IDX685"></A>
991 Generate sorted output. Note that using this option makes it much harder
992 for the translator to understand each message's context.
994 <DT><SAMP>‘--sort-by-file’</SAMP>
996 <A NAME="IDX686"></A>
997 Sort output by file location.
1003 <H3><A NAME="SEC100" HREF="gettext_toc.html#TOC100">9.3.6 Informative output</A></H3>
1007 <DT><SAMP>‘-h’</SAMP>
1009 <DT><SAMP>‘--help’</SAMP>
1011 <A NAME="IDX687"></A>
1012 <A NAME="IDX688"></A>
1013 Display this help and exit.
1015 <DT><SAMP>‘-V’</SAMP>
1017 <DT><SAMP>‘--version’</SAMP>
1019 <A NAME="IDX689"></A>
1020 <A NAME="IDX690"></A>
1021 Output version information and exit.
1027 <H3><A NAME="SEC101" HREF="gettext_toc.html#TOC101">9.3.7 Examples</A></H3>
1030 To extract the messages that come from the source files
1031 <CODE>gnulib-lib/error.c</CODE> and <CODE>gnulib-lib/getopt.c</CODE>:
1036 msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po
1040 To extract the messages that contain the string “Please specify” in the
1046 msggrep --msgid -F -e 'Please specify' input.po
1050 To extract the messages that have a context specifier of either “Menu>File”
1051 or “Menu>Edit” or a submenu of them:
1056 msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po
1060 To extract the messages whose translation contains one of the strings in the
1061 file <CODE>wordlist.txt</CODE>:
1066 msggrep --msgstr -F -f wordlist.txt input.po
1071 <H2><A NAME="SEC102" HREF="gettext_toc.html#TOC102">9.4 Invoking the <CODE>msgfilter</CODE> Program</A></H2>
1074 <A NAME="IDX691"></A>
1075 <A NAME="IDX692"></A>
1078 msgfilter [<VAR>option</VAR>] <VAR>filter</VAR> [<VAR>filter-option</VAR>]
1082 <A NAME="IDX693"></A>
1083 The <CODE>msgfilter</CODE> program applies a filter to all translations of a
1084 translation catalog.
1088 <A NAME="IDX694"></A>
1089 <A NAME="IDX695"></A>
1090 <A NAME="IDX696"></A>
1091 <A NAME="IDX697"></A>
1092 <A NAME="IDX698"></A>
1093 <A NAME="IDX699"></A>
1094 <A NAME="IDX700"></A>
1095 <A NAME="IDX701"></A>
1096 During each <VAR>filter</VAR> invocation, the environment variable
1097 <CODE>MSGFILTER_MSGID</CODE> is bound to the message's msgid, and the environment
1098 variable <CODE>MSGFILTER_LOCATION</CODE> is bound to the location in the PO file
1099 of the message. If the message has a context, the environment variable
1100 <CODE>MSGFILTER_MSGCTXT</CODE> is bound to the message's msgctxt, otherwise it is
1101 unbound. If the message has a plural form, environment variable
1102 <CODE>MSGFILTER_MSGID_PLURAL</CODE> is bound to the message's msgid_plural and
1103 <CODE>MSGFILTER_PLURAL_FORM</CODE> is bound to the order number of the plural
1104 actually processed (starting with 0), otherwise both are unbound.
1105 If the message has a previous msgid (added by <CODE>msgmerge</CODE>),
1106 environment variable <CODE>MSGFILTER_PREV_MSGCTXT</CODE> is bound to the
1107 message's previous msgctxt, <CODE>MSGFILTER_PREV_MSGID</CODE> is bound to
1108 the previous msgid, and <CODE>MSGFILTER_PREV_MSGID_PLURAL</CODE> is bound to
1109 the previous msgid_plural.
1114 <H3><A NAME="SEC103" HREF="gettext_toc.html#TOC103">9.4.1 Input file location</A></H3>
1118 <DT><SAMP>‘-i <VAR>inputfile</VAR>’</SAMP>
1120 <DT><SAMP>‘--input=<VAR>inputfile</VAR>’</SAMP>
1122 <A NAME="IDX702"></A>
1123 <A NAME="IDX703"></A>
1126 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
1128 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
1130 <A NAME="IDX704"></A>
1131 <A NAME="IDX705"></A>
1132 Add <VAR>directory</VAR> to the list of directories. Source files are
1133 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
1134 file will be written relative to the current directory, though.
1139 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
1144 <H3><A NAME="SEC104" HREF="gettext_toc.html#TOC104">9.4.2 Output file location</A></H3>
1148 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
1150 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
1152 <A NAME="IDX706"></A>
1153 <A NAME="IDX707"></A>
1154 Write output to specified file.
1159 The results are written to standard output if no output file is specified
1160 or if it is <SAMP>‘-’</SAMP>.
1165 <H3><A NAME="SEC105" HREF="gettext_toc.html#TOC105">9.4.3 The filter</A></H3>
1168 The <VAR>filter</VAR> can be any program that reads a translation from standard
1169 input and writes a modified translation to standard output. A frequently
1170 used filter is <SAMP>‘sed’</SAMP>. A few particular built-in filters are also
1176 <DT><SAMP>‘--newline’</SAMP>
1178 <A NAME="IDX708"></A>
1179 Add newline at the end of each input line and also strip the ending
1180 newline from the output line.
1185 <A NAME="IDX709"></A>
1186 Note: If the filter is not a built-in filter, you have to care about encodings:
1187 It is your responsibility to ensure that the <VAR>filter</VAR> can cope
1188 with input encoded in the translation catalog's encoding. If the
1189 <VAR>filter</VAR> wants input in a particular encoding, you can in a first step
1190 convert the translation catalog to that encoding using the <SAMP>‘msgconv’</SAMP>
1191 program, before invoking <SAMP>‘msgfilter’</SAMP>. If the <VAR>filter</VAR> wants input
1192 in the locale's encoding, but you want to avoid the locale's encoding, then
1193 you can first convert the translation catalog to UTF-8 using the
1194 <SAMP>‘msgconv’</SAMP> program and then make <SAMP>‘msgfilter’</SAMP> work in an UTF-8
1195 locale, by using the <CODE>LC_ALL</CODE> environment variable.
1199 <A NAME="IDX710"></A>
1200 Note: Most translations in a translation catalog don't end with a
1201 newline character. For this reason, unless the <CODE>--newline</CODE>
1202 option is used, it is important that the <VAR>filter</VAR> recognizes its
1203 last input line even if it ends without a newline, and that it doesn't
1204 add an undesired trailing newline at the end. The <SAMP>‘sed’</SAMP> program on
1205 some platforms is known to ignore the last line of input if it is not
1206 terminated with a newline. You can use GNU <CODE>sed</CODE> instead; it does
1207 not have this limitation.
1212 <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>
1216 <DT><SAMP>‘-e <VAR>script</VAR>’</SAMP>
1218 <DT><SAMP>‘--expression=<VAR>script</VAR>’</SAMP>
1220 <A NAME="IDX711"></A>
1221 <A NAME="IDX712"></A>
1222 Add <VAR>script</VAR> to the commands to be executed.
1224 <DT><SAMP>‘-f <VAR>scriptfile</VAR>’</SAMP>
1226 <DT><SAMP>‘--file=<VAR>scriptfile</VAR>’</SAMP>
1228 <A NAME="IDX713"></A>
1229 <A NAME="IDX714"></A>
1230 Add the contents of <VAR>scriptfile</VAR> to the commands to be executed.
1232 <DT><SAMP>‘-n’</SAMP>
1234 <DT><SAMP>‘--quiet’</SAMP>
1236 <DT><SAMP>‘--silent’</SAMP>
1238 <A NAME="IDX715"></A>
1239 <A NAME="IDX716"></A>
1240 <A NAME="IDX717"></A>
1241 Suppress automatic printing of pattern space.
1247 <H3><A NAME="SEC107" HREF="gettext_toc.html#TOC107">9.4.5 Built-in <VAR>filter</VAR>s</A></H3>
1250 <A NAME="IDX718"></A>
1251 <A NAME="IDX719"></A>
1252 The filter <SAMP>‘recode-sr-latin’</SAMP> is recognized as a built-in filter.
1253 The command <SAMP>‘recode-sr-latin’</SAMP> converts Serbian text, written in the
1254 Cyrillic script, to the Latin script.
1255 The command <SAMP>‘msgfilter recode-sr-latin’</SAMP> applies this conversion to the
1256 translations of a PO file. Thus, it can be used to convert an <TT>‘sr.po’</TT>
1257 file to an <TT>‘sr@latin.po’</TT> file.
1261 <A NAME="IDX720"></A>
1262 The filter <SAMP>‘quot’</SAMP> is recognized as a built-in filter.
1263 The command <SAMP>‘msgfilter quot’</SAMP> converts any quotations surrounded
1264 by a pair of <SAMP>‘"’</SAMP>, <SAMP>‘'’</SAMP>, and <SAMP>‘`’</SAMP>.
1268 <A NAME="IDX721"></A>
1269 The filter <SAMP>‘boldquot’</SAMP> is recognized as a built-in filter.
1270 The command <SAMP>‘msgfilter boldquot’</SAMP> converts any quotations
1271 surrounded by a pair of <SAMP>‘"’</SAMP>, <SAMP>‘'’</SAMP>, and <SAMP>‘`’</SAMP>, also adding the
1272 VT100 escape sequences to the text to decorate it as bold.
1276 The use of built-in filters is not sensitive to the current locale's encoding.
1277 Moreover, when used with a built-in filter, <SAMP>‘msgfilter’</SAMP> can automatically
1278 convert the message catalog to the UTF-8 encoding when needed.
1283 <H3><A NAME="SEC108" HREF="gettext_toc.html#TOC108">9.4.6 Input file syntax</A></H3>
1287 <DT><SAMP>‘-P’</SAMP>
1289 <DT><SAMP>‘--properties-input’</SAMP>
1291 <A NAME="IDX722"></A>
1292 <A NAME="IDX723"></A>
1293 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
1294 syntax, not in PO file syntax.
1296 <DT><SAMP>‘--stringtable-input’</SAMP>
1298 <A NAME="IDX724"></A>
1299 Assume the input file is a NeXTstep/GNUstep localized resource file in
1300 <CODE>.strings</CODE> syntax, not in PO file syntax.
1306 <H3><A NAME="SEC109" HREF="gettext_toc.html#TOC109">9.4.7 Output details</A></H3>
1310 <DT><SAMP>‘--color’</SAMP>
1312 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
1314 <A NAME="IDX725"></A>
1315 Specify whether or when to use colors and other text attributes.
1316 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
1318 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
1320 <A NAME="IDX726"></A>
1321 Specify the CSS style rule file to use for <CODE>--color</CODE>.
1322 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
1324 <DT><SAMP>‘--force-po’</SAMP>
1326 <A NAME="IDX727"></A>
1327 Always write an output file even if it contains no message.
1329 <DT><SAMP>‘--indent’</SAMP>
1331 <A NAME="IDX728"></A>
1332 Write the .po file using indented style.
1334 <DT><SAMP>‘--keep-header’</SAMP>
1336 <A NAME="IDX729"></A>
1337 Keep the header entry, i.e. the message with <SAMP>‘msgid ""’</SAMP>, unmodified,
1338 instead of filtering it. By default, the header entry is subject to
1339 filtering like any other message.
1341 <DT><SAMP>‘--no-location’</SAMP>
1343 <A NAME="IDX730"></A>
1344 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
1346 <DT><SAMP>‘-n’</SAMP>
1348 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
1350 <A NAME="IDX731"></A>
1351 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
1353 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
1354 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
1355 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
1356 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
1357 suppresses the lines (same as <CODE>--no-location</CODE>).
1359 <DT><SAMP>‘--strict’</SAMP>
1361 <A NAME="IDX732"></A>
1362 Write out a strict Uniforum conforming PO file. Note that this
1363 Uniforum format should be avoided because it doesn't support the
1366 <DT><SAMP>‘-p’</SAMP>
1368 <DT><SAMP>‘--properties-output’</SAMP>
1370 <A NAME="IDX733"></A>
1371 <A NAME="IDX734"></A>
1372 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
1373 that this file format doesn't support plural forms and silently drops
1376 <DT><SAMP>‘--stringtable-output’</SAMP>
1378 <A NAME="IDX735"></A>
1379 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
1380 Note that this file format doesn't support plural forms.
1382 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
1384 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
1386 <A NAME="IDX736"></A>
1387 <A NAME="IDX737"></A>
1388 Set the output page width. Long strings in the output files will be
1389 split across multiple lines in order to ensure that each line's width
1390 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
1392 <DT><SAMP>‘--no-wrap’</SAMP>
1394 <A NAME="IDX738"></A>
1395 Do not break long message lines. Message lines whose width exceeds the
1396 output page width will not be split into several lines. Only file reference
1397 lines which are wider than the output page width will be split.
1399 <DT><SAMP>‘-s’</SAMP>
1401 <DT><SAMP>‘--sort-output’</SAMP>
1403 <A NAME="IDX739"></A>
1404 <A NAME="IDX740"></A>
1405 Generate sorted output. Note that using this option makes it much harder
1406 for the translator to understand each message's context.
1408 <DT><SAMP>‘-F’</SAMP>
1410 <DT><SAMP>‘--sort-by-file’</SAMP>
1412 <A NAME="IDX741"></A>
1413 <A NAME="IDX742"></A>
1414 Sort output by file location.
1420 <H3><A NAME="SEC110" HREF="gettext_toc.html#TOC110">9.4.8 Informative output</A></H3>
1424 <DT><SAMP>‘-h’</SAMP>
1426 <DT><SAMP>‘--help’</SAMP>
1428 <A NAME="IDX743"></A>
1429 <A NAME="IDX744"></A>
1430 Display this help and exit.
1432 <DT><SAMP>‘-V’</SAMP>
1434 <DT><SAMP>‘--version’</SAMP>
1436 <A NAME="IDX745"></A>
1437 <A NAME="IDX746"></A>
1438 Output version information and exit.
1444 <H3><A NAME="SEC111" HREF="gettext_toc.html#TOC111">9.4.9 Examples</A></H3>
1447 To convert German translations to Swiss orthography (in an UTF-8 locale):
1452 msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g'
1456 To convert Serbian translations in Cyrillic script to Latin script:
1461 msgfilter recode-sr-latin < sr.po
1466 <H2><A NAME="SEC112" HREF="gettext_toc.html#TOC112">9.5 Invoking the <CODE>msguniq</CODE> Program</A></H2>
1469 <A NAME="IDX747"></A>
1470 <A NAME="IDX748"></A>
1473 msguniq [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
1477 <A NAME="IDX749"></A>
1478 <A NAME="IDX750"></A>
1479 The <CODE>msguniq</CODE> program unifies duplicate translations in a translation
1480 catalog. It finds duplicate translations of the same message ID. Such
1481 duplicates are invalid input for other programs like <CODE>msgfmt</CODE>,
1482 <CODE>msgmerge</CODE> or <CODE>msgcat</CODE>. By default, duplicates are merged
1483 together. When using the <SAMP>‘--repeated’</SAMP> option, only duplicates are
1484 output, and all other messages are discarded. Comments and extracted
1485 comments will be cumulated, except that if <SAMP>‘--use-first’</SAMP> is
1486 specified, they will be taken from the first translation. File positions
1487 will be cumulated. When using the <SAMP>‘--unique’</SAMP> option, duplicates are
1493 <H3><A NAME="SEC113" HREF="gettext_toc.html#TOC113">9.5.1 Input file location</A></H3>
1497 <DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP>
1501 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
1503 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
1505 <A NAME="IDX751"></A>
1506 <A NAME="IDX752"></A>
1507 Add <VAR>directory</VAR> to the list of directories. Source files are
1508 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
1509 file will be written relative to the current directory, though.
1514 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
1519 <H3><A NAME="SEC114" HREF="gettext_toc.html#TOC114">9.5.2 Output file location</A></H3>
1523 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
1525 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
1527 <A NAME="IDX753"></A>
1528 <A NAME="IDX754"></A>
1529 Write output to specified file.
1534 The results are written to standard output if no output file is specified
1535 or if it is <SAMP>‘-’</SAMP>.
1540 <H3><A NAME="SEC115" HREF="gettext_toc.html#TOC115">9.5.3 Message selection</A></H3>
1544 <DT><SAMP>‘-d’</SAMP>
1546 <DT><SAMP>‘--repeated’</SAMP>
1548 <A NAME="IDX755"></A>
1549 <A NAME="IDX756"></A>
1550 Print only duplicates.
1552 <DT><SAMP>‘-u’</SAMP>
1554 <DT><SAMP>‘--unique’</SAMP>
1556 <A NAME="IDX757"></A>
1557 <A NAME="IDX758"></A>
1558 Print only unique messages, discard duplicates.
1564 <H3><A NAME="SEC116" HREF="gettext_toc.html#TOC116">9.5.4 Input file syntax</A></H3>
1568 <DT><SAMP>‘-P’</SAMP>
1570 <DT><SAMP>‘--properties-input’</SAMP>
1572 <A NAME="IDX759"></A>
1573 <A NAME="IDX760"></A>
1574 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
1575 syntax, not in PO file syntax.
1577 <DT><SAMP>‘--stringtable-input’</SAMP>
1579 <A NAME="IDX761"></A>
1580 Assume the input file is a NeXTstep/GNUstep localized resource file in
1581 <CODE>.strings</CODE> syntax, not in PO file syntax.
1587 <H3><A NAME="SEC117" HREF="gettext_toc.html#TOC117">9.5.5 Output details</A></H3>
1591 <DT><SAMP>‘-t’</SAMP>
1593 <DT><SAMP>‘--to-code=<VAR>name</VAR>’</SAMP>
1595 <A NAME="IDX762"></A>
1596 <A NAME="IDX763"></A>
1597 Specify encoding for output.
1599 <DT><SAMP>‘--use-first’</SAMP>
1601 <A NAME="IDX764"></A>
1602 Use first available translation for each message. Don't merge several
1603 translations into one.
1605 <DT><SAMP>‘--color’</SAMP>
1607 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
1609 <A NAME="IDX765"></A>
1610 Specify whether or when to use colors and other text attributes.
1611 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
1613 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
1615 <A NAME="IDX766"></A>
1616 Specify the CSS style rule file to use for <CODE>--color</CODE>.
1617 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
1619 <DT><SAMP>‘--force-po’</SAMP>
1621 <A NAME="IDX767"></A>
1622 Always write an output file even if it contains no message.
1624 <DT><SAMP>‘-i’</SAMP>
1626 <DT><SAMP>‘--indent’</SAMP>
1628 <A NAME="IDX768"></A>
1629 <A NAME="IDX769"></A>
1630 Write the .po file using indented style.
1632 <DT><SAMP>‘--no-location’</SAMP>
1634 <A NAME="IDX770"></A>
1635 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
1637 <DT><SAMP>‘-n’</SAMP>
1639 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
1641 <A NAME="IDX771"></A>
1642 <A NAME="IDX772"></A>
1643 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
1645 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
1646 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
1647 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
1648 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
1649 suppresses the lines (same as <CODE>--no-location</CODE>).
1651 <DT><SAMP>‘--strict’</SAMP>
1653 <A NAME="IDX773"></A>
1654 Write out a strict Uniforum conforming PO file. Note that this
1655 Uniforum format should be avoided because it doesn't support the
1658 <DT><SAMP>‘-p’</SAMP>
1660 <DT><SAMP>‘--properties-output’</SAMP>
1662 <A NAME="IDX774"></A>
1663 <A NAME="IDX775"></A>
1664 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
1665 that this file format doesn't support plural forms and silently drops
1668 <DT><SAMP>‘--stringtable-output’</SAMP>
1670 <A NAME="IDX776"></A>
1671 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
1672 Note that this file format doesn't support plural forms.
1674 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
1676 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
1678 <A NAME="IDX777"></A>
1679 <A NAME="IDX778"></A>
1680 Set the output page width. Long strings in the output files will be
1681 split across multiple lines in order to ensure that each line's width
1682 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
1684 <DT><SAMP>‘--no-wrap’</SAMP>
1686 <A NAME="IDX779"></A>
1687 Do not break long message lines. Message lines whose width exceeds the
1688 output page width will not be split into several lines. Only file reference
1689 lines which are wider than the output page width will be split.
1691 <DT><SAMP>‘-s’</SAMP>
1693 <DT><SAMP>‘--sort-output’</SAMP>
1695 <A NAME="IDX780"></A>
1696 <A NAME="IDX781"></A>
1697 Generate sorted output. Note that using this option makes it much harder
1698 for the translator to understand each message's context.
1700 <DT><SAMP>‘-F’</SAMP>
1702 <DT><SAMP>‘--sort-by-file’</SAMP>
1704 <A NAME="IDX782"></A>
1705 <A NAME="IDX783"></A>
1706 Sort output by file location.
1712 <H3><A NAME="SEC118" HREF="gettext_toc.html#TOC118">9.5.6 Informative output</A></H3>
1716 <DT><SAMP>‘-h’</SAMP>
1718 <DT><SAMP>‘--help’</SAMP>
1720 <A NAME="IDX784"></A>
1721 <A NAME="IDX785"></A>
1722 Display this help and exit.
1724 <DT><SAMP>‘-V’</SAMP>
1726 <DT><SAMP>‘--version’</SAMP>
1728 <A NAME="IDX786"></A>
1729 <A NAME="IDX787"></A>
1730 Output version information and exit.
1736 <H2><A NAME="SEC119" HREF="gettext_toc.html#TOC119">9.6 Invoking the <CODE>msgcomm</CODE> Program</A></H2>
1739 <A NAME="IDX788"></A>
1740 <A NAME="IDX789"></A>
1743 msgcomm [<VAR>option</VAR>] [<VAR>inputfile</VAR>]...
1747 <A NAME="IDX790"></A>
1748 The <CODE>msgcomm</CODE> program finds messages which are common to two or more
1749 of the specified PO files.
1750 By using the <CODE>--more-than</CODE> option, greater commonality may be requested
1751 before messages are printed. Conversely, the <CODE>--less-than</CODE> option may be
1752 used to specify less commonality before messages are printed (i.e.
1753 <SAMP>‘--less-than=2’</SAMP> will only print the unique messages). Translations,
1754 comments and extracted comments will be preserved, but only from the first
1755 PO file to define them. File positions from all PO files will be
1761 <H3><A NAME="SEC120" HREF="gettext_toc.html#TOC120">9.6.1 Input file location</A></H3>
1765 <DT><SAMP>‘<VAR>inputfile</VAR> ...’</SAMP>
1769 <DT><SAMP>‘-f <VAR>file</VAR>’</SAMP>
1771 <DT><SAMP>‘--files-from=<VAR>file</VAR>’</SAMP>
1773 <A NAME="IDX791"></A>
1774 <A NAME="IDX792"></A>
1775 Read the names of the input files from <VAR>file</VAR> instead of getting
1776 them from the command line.
1778 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
1780 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
1782 <A NAME="IDX793"></A>
1783 <A NAME="IDX794"></A>
1784 Add <VAR>directory</VAR> to the list of directories. Source files are
1785 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
1786 file will be written relative to the current directory, though.
1791 If <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read.
1796 <H3><A NAME="SEC121" HREF="gettext_toc.html#TOC121">9.6.2 Output file location</A></H3>
1800 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
1802 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
1804 <A NAME="IDX795"></A>
1805 <A NAME="IDX796"></A>
1806 Write output to specified file.
1811 The results are written to standard output if no output file is specified
1812 or if it is <SAMP>‘-’</SAMP>.
1817 <H3><A NAME="SEC122" HREF="gettext_toc.html#TOC122">9.6.3 Message selection</A></H3>
1821 <DT><SAMP>‘-< <VAR>number</VAR>’</SAMP>
1823 <DT><SAMP>‘--less-than=<VAR>number</VAR>’</SAMP>
1825 <A NAME="IDX797"></A>
1826 <A NAME="IDX798"></A>
1827 Print messages with less than <VAR>number</VAR> definitions, defaults to infinite
1830 <DT><SAMP>‘-> <VAR>number</VAR>’</SAMP>
1832 <DT><SAMP>‘--more-than=<VAR>number</VAR>’</SAMP>
1834 <A NAME="IDX799"></A>
1835 <A NAME="IDX800"></A>
1836 Print messages with more than <VAR>number</VAR> definitions, defaults to 1 if not
1839 <DT><SAMP>‘-u’</SAMP>
1841 <DT><SAMP>‘--unique’</SAMP>
1843 <A NAME="IDX801"></A>
1844 <A NAME="IDX802"></A>
1845 Shorthand for <SAMP>‘--less-than=2’</SAMP>. Requests that only unique messages be
1852 <H3><A NAME="SEC123" HREF="gettext_toc.html#TOC123">9.6.4 Input file syntax</A></H3>
1856 <DT><SAMP>‘-P’</SAMP>
1858 <DT><SAMP>‘--properties-input’</SAMP>
1860 <A NAME="IDX803"></A>
1861 <A NAME="IDX804"></A>
1862 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
1863 syntax, not in PO file syntax.
1865 <DT><SAMP>‘--stringtable-input’</SAMP>
1867 <A NAME="IDX805"></A>
1868 Assume the input files are NeXTstep/GNUstep localized resource files in
1869 <CODE>.strings</CODE> syntax, not in PO file syntax.
1875 <H3><A NAME="SEC124" HREF="gettext_toc.html#TOC124">9.6.5 Output details</A></H3>
1879 <DT><SAMP>‘--color’</SAMP>
1881 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
1883 <A NAME="IDX806"></A>
1884 Specify whether or when to use colors and other text attributes.
1885 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
1887 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
1889 <A NAME="IDX807"></A>
1890 Specify the CSS style rule file to use for <CODE>--color</CODE>.
1891 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
1893 <DT><SAMP>‘--force-po’</SAMP>
1895 <A NAME="IDX808"></A>
1896 Always write an output file even if it contains no message.
1898 <DT><SAMP>‘-i’</SAMP>
1900 <DT><SAMP>‘--indent’</SAMP>
1902 <A NAME="IDX809"></A>
1903 <A NAME="IDX810"></A>
1904 Write the .po file using indented style.
1906 <DT><SAMP>‘--no-location’</SAMP>
1908 <A NAME="IDX811"></A>
1909 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
1911 <DT><SAMP>‘-n’</SAMP>
1913 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
1915 <A NAME="IDX812"></A>
1916 <A NAME="IDX813"></A>
1917 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
1919 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
1920 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
1921 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
1922 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
1923 suppresses the lines (same as <CODE>--no-location</CODE>).
1925 <DT><SAMP>‘--strict’</SAMP>
1927 <A NAME="IDX814"></A>
1928 Write out a strict Uniforum conforming PO file. Note that this
1929 Uniforum format should be avoided because it doesn't support the
1932 <DT><SAMP>‘-p’</SAMP>
1934 <DT><SAMP>‘--properties-output’</SAMP>
1936 <A NAME="IDX815"></A>
1937 <A NAME="IDX816"></A>
1938 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
1939 that this file format doesn't support plural forms and silently drops
1942 <DT><SAMP>‘--stringtable-output’</SAMP>
1944 <A NAME="IDX817"></A>
1945 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
1946 Note that this file format doesn't support plural forms.
1948 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
1950 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
1952 <A NAME="IDX818"></A>
1953 <A NAME="IDX819"></A>
1954 Set the output page width. Long strings in the output files will be
1955 split across multiple lines in order to ensure that each line's width
1956 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
1958 <DT><SAMP>‘--no-wrap’</SAMP>
1960 <A NAME="IDX820"></A>
1961 Do not break long message lines. Message lines whose width exceeds the
1962 output page width will not be split into several lines. Only file reference
1963 lines which are wider than the output page width will be split.
1965 <DT><SAMP>‘-s’</SAMP>
1967 <DT><SAMP>‘--sort-output’</SAMP>
1969 <A NAME="IDX821"></A>
1970 <A NAME="IDX822"></A>
1971 Generate sorted output. Note that using this option makes it much harder
1972 for the translator to understand each message's context.
1974 <DT><SAMP>‘-F’</SAMP>
1976 <DT><SAMP>‘--sort-by-file’</SAMP>
1978 <A NAME="IDX823"></A>
1979 <A NAME="IDX824"></A>
1980 Sort output by file location.
1982 <DT><SAMP>‘--omit-header’</SAMP>
1984 <A NAME="IDX825"></A>
1985 Don't write header with <SAMP>‘msgid ""’</SAMP> entry.
1991 <H3><A NAME="SEC125" HREF="gettext_toc.html#TOC125">9.6.6 Informative output</A></H3>
1995 <DT><SAMP>‘-h’</SAMP>
1997 <DT><SAMP>‘--help’</SAMP>
1999 <A NAME="IDX826"></A>
2000 <A NAME="IDX827"></A>
2001 Display this help and exit.
2003 <DT><SAMP>‘-V’</SAMP>
2005 <DT><SAMP>‘--version’</SAMP>
2007 <A NAME="IDX828"></A>
2008 <A NAME="IDX829"></A>
2009 Output version information and exit.
2015 <H2><A NAME="SEC126" HREF="gettext_toc.html#TOC126">9.7 Invoking the <CODE>msgcmp</CODE> Program</A></H2>
2018 <A NAME="IDX830"></A>
2019 <A NAME="IDX831"></A>
2022 msgcmp [<VAR>option</VAR>] <VAR>def</VAR>.po <VAR>ref</VAR>.pot
2026 <A NAME="IDX832"></A>
2027 The <CODE>msgcmp</CODE> program compares two Uniforum style .po files to check that
2028 both contain the same set of msgid strings. The <VAR>def</VAR>.po file is an
2029 existing PO file with the translations. The <VAR>ref</VAR>.pot file is the last
2030 created PO file, or a PO Template file (generally created by <CODE>xgettext</CODE>).
2031 This is useful for checking that you have translated each and every message
2032 in your program. Where an exact match cannot be found, fuzzy matching is
2033 used to produce better diagnostics.
2038 <H3><A NAME="SEC127" HREF="gettext_toc.html#TOC127">9.7.1 Input file location</A></H3>
2042 <DT><SAMP>‘<VAR>def</VAR>.po’</SAMP>
2046 <DT><SAMP>‘<VAR>ref</VAR>.pot’</SAMP>
2048 References to the sources.
2050 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
2052 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
2054 <A NAME="IDX833"></A>
2055 <A NAME="IDX834"></A>
2056 Add <VAR>directory</VAR> to the list of directories. Source files are
2057 searched relative to this list of directories.
2063 <H3><A NAME="SEC128" HREF="gettext_toc.html#TOC128">9.7.2 Operation modifiers</A></H3>
2067 <DT><SAMP>‘-m’</SAMP>
2069 <DT><SAMP>‘--multi-domain’</SAMP>
2071 <A NAME="IDX835"></A>
2072 <A NAME="IDX836"></A>
2073 Apply <VAR>ref</VAR>.pot to each of the domains in <VAR>def</VAR>.po.
2075 <DT><SAMP>‘-N’</SAMP>
2077 <DT><SAMP>‘--no-fuzzy-matching’</SAMP>
2079 <A NAME="IDX837"></A>
2080 <A NAME="IDX838"></A>
2081 Do not use fuzzy matching when an exact match is not found. This may speed
2082 up the operation considerably.
2084 <DT><SAMP>‘--use-fuzzy’</SAMP>
2086 <A NAME="IDX839"></A>
2087 Consider fuzzy messages in the <VAR>def</VAR>.po file like translated messages.
2088 Note that using this option is usually wrong, because fuzzy messages are
2089 exactly those which have not been validated by a human translator.
2091 <DT><SAMP>‘--use-untranslated’</SAMP>
2093 <A NAME="IDX840"></A>
2094 Consider untranslated messages in the <VAR>def</VAR>.po file like translated
2095 messages. Note that using this option is usually wrong.
2101 <H3><A NAME="SEC129" HREF="gettext_toc.html#TOC129">9.7.3 Input file syntax</A></H3>
2105 <DT><SAMP>‘-P’</SAMP>
2107 <DT><SAMP>‘--properties-input’</SAMP>
2109 <A NAME="IDX841"></A>
2110 <A NAME="IDX842"></A>
2111 Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE>
2112 syntax, not in PO file syntax.
2114 <DT><SAMP>‘--stringtable-input’</SAMP>
2116 <A NAME="IDX843"></A>
2117 Assume the input files are NeXTstep/GNUstep localized resource files in
2118 <CODE>.strings</CODE> syntax, not in PO file syntax.
2124 <H3><A NAME="SEC130" HREF="gettext_toc.html#TOC130">9.7.4 Informative output</A></H3>
2128 <DT><SAMP>‘-h’</SAMP>
2130 <DT><SAMP>‘--help’</SAMP>
2132 <A NAME="IDX844"></A>
2133 <A NAME="IDX845"></A>
2134 Display this help and exit.
2136 <DT><SAMP>‘-V’</SAMP>
2138 <DT><SAMP>‘--version’</SAMP>
2140 <A NAME="IDX846"></A>
2141 <A NAME="IDX847"></A>
2142 Output version information and exit.
2148 <H2><A NAME="SEC131" HREF="gettext_toc.html#TOC131">9.8 Invoking the <CODE>msgattrib</CODE> Program</A></H2>
2151 <A NAME="IDX848"></A>
2152 <A NAME="IDX849"></A>
2155 msgattrib [<VAR>option</VAR>] [<VAR>inputfile</VAR>]
2159 <A NAME="IDX850"></A>
2160 <A NAME="IDX851"></A>
2161 The <CODE>msgattrib</CODE> program filters the messages of a translation catalog
2162 according to their attributes, and manipulates the attributes.
2167 <H3><A NAME="SEC132" HREF="gettext_toc.html#TOC132">9.8.1 Input file location</A></H3>
2171 <DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP>
2175 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
2177 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
2179 <A NAME="IDX852"></A>
2180 <A NAME="IDX853"></A>
2181 Add <VAR>directory</VAR> to the list of directories. Source files are
2182 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
2183 file will be written relative to the current directory, though.
2188 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
2193 <H3><A NAME="SEC133" HREF="gettext_toc.html#TOC133">9.8.2 Output file location</A></H3>
2197 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
2199 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
2201 <A NAME="IDX854"></A>
2202 <A NAME="IDX855"></A>
2203 Write output to specified file.
2208 The results are written to standard output if no output file is specified
2209 or if it is <SAMP>‘-’</SAMP>.
2214 <H3><A NAME="SEC134" HREF="gettext_toc.html#TOC134">9.8.3 Message selection</A></H3>
2218 <DT><SAMP>‘--translated’</SAMP>
2220 <A NAME="IDX856"></A>
2221 Keep translated messages, remove untranslated messages.
2223 <DT><SAMP>‘--untranslated’</SAMP>
2225 <A NAME="IDX857"></A>
2226 Keep untranslated messages, remove translated messages.
2228 <DT><SAMP>‘--no-fuzzy’</SAMP>
2230 <A NAME="IDX858"></A>
2235 <DT><SAMP>‘--only-fuzzy’</SAMP>
2237 <A NAME="IDX859"></A>
2240 marked messages, remove all other messages.
2242 <DT><SAMP>‘--no-obsolete’</SAMP>
2244 <A NAME="IDX860"></A>
2245 Remove obsolete #~ messages.
2247 <DT><SAMP>‘--only-obsolete’</SAMP>
2249 <A NAME="IDX861"></A>
2250 Keep obsolete #~ messages, remove all other messages.
2256 <H3><A NAME="SEC135" HREF="gettext_toc.html#TOC135">9.8.4 Attribute manipulation</A></H3>
2259 <A NAME="IDX862"></A>
2260 Attributes are modified after the message selection/removal has been
2261 performed. If the <SAMP>‘--only-file’</SAMP> or <SAMP>‘--ignore-file’</SAMP> option is
2262 specified, the attribute modification is applied only to those messages
2263 that are listed in the <VAR>only-file</VAR> and not listed in the
2264 <VAR>ignore-file</VAR>.
2269 <DT><SAMP>‘--set-fuzzy’</SAMP>
2271 <A NAME="IDX863"></A>
2275 <DT><SAMP>‘--clear-fuzzy’</SAMP>
2277 <A NAME="IDX864"></A>
2281 <DT><SAMP>‘--set-obsolete’</SAMP>
2283 <A NAME="IDX865"></A>
2284 Set all messages obsolete.
2286 <DT><SAMP>‘--clear-obsolete’</SAMP>
2288 <A NAME="IDX866"></A>
2289 Set all messages non-obsolete.
2291 <DT><SAMP>‘--previous’</SAMP>
2293 <A NAME="IDX867"></A>
2296 mark, keep “previous msgid” of translated messages.
2298 <DT><SAMP>‘--clear-previous’</SAMP>
2300 <A NAME="IDX868"></A>
2301 Remove the “previous msgid” (<SAMP>‘#|’</SAMP>) comments from all messages.
2303 <DT><SAMP>‘--empty’</SAMP>
2305 <A NAME="IDX869"></A>
2308 mark, also set msgstr empty.
2310 <DT><SAMP>‘--only-file=<VAR>file</VAR>’</SAMP>
2312 <A NAME="IDX870"></A>
2313 Limit the attribute changes to entries that are listed in <VAR>file</VAR>.
2314 <VAR>file</VAR> should be a PO or POT file.
2316 <DT><SAMP>‘--ignore-file=<VAR>file</VAR>’</SAMP>
2318 <A NAME="IDX871"></A>
2319 Limit the attribute changes to entries that are not listed in <VAR>file</VAR>.
2320 <VAR>file</VAR> should be a PO or POT file.
2322 <DT><SAMP>‘--fuzzy’</SAMP>
2324 <A NAME="IDX872"></A>
2325 Synonym for <SAMP>‘--only-fuzzy --clear-fuzzy’</SAMP>: It keeps only the fuzzy
2326 messages and removes their
2330 <DT><SAMP>‘--obsolete’</SAMP>
2332 <A NAME="IDX873"></A>
2333 Synonym for <SAMP>‘--only-obsolete --clear-obsolete’</SAMP>: It keeps only the
2334 obsolete messages and makes them non-obsolete.
2340 <H3><A NAME="SEC136" HREF="gettext_toc.html#TOC136">9.8.5 Input file syntax</A></H3>
2344 <DT><SAMP>‘-P’</SAMP>
2346 <DT><SAMP>‘--properties-input’</SAMP>
2348 <A NAME="IDX874"></A>
2349 <A NAME="IDX875"></A>
2350 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
2351 syntax, not in PO file syntax.
2353 <DT><SAMP>‘--stringtable-input’</SAMP>
2355 <A NAME="IDX876"></A>
2356 Assume the input file is a NeXTstep/GNUstep localized resource file in
2357 <CODE>.strings</CODE> syntax, not in PO file syntax.
2363 <H3><A NAME="SEC137" HREF="gettext_toc.html#TOC137">9.8.6 Output details</A></H3>
2367 <DT><SAMP>‘--color’</SAMP>
2369 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
2371 <A NAME="IDX877"></A>
2372 Specify whether or when to use colors and other text attributes.
2373 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
2375 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
2377 <A NAME="IDX878"></A>
2378 Specify the CSS style rule file to use for <CODE>--color</CODE>.
2379 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
2381 <DT><SAMP>‘--force-po’</SAMP>
2383 <A NAME="IDX879"></A>
2384 Always write an output file even if it contains no message.
2386 <DT><SAMP>‘-i’</SAMP>
2388 <DT><SAMP>‘--indent’</SAMP>
2390 <A NAME="IDX880"></A>
2391 <A NAME="IDX881"></A>
2392 Write the .po file using indented style.
2394 <DT><SAMP>‘--no-location’</SAMP>
2396 <A NAME="IDX882"></A>
2397 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
2399 <DT><SAMP>‘-n’</SAMP>
2401 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
2403 <A NAME="IDX883"></A>
2404 <A NAME="IDX884"></A>
2405 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
2407 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
2408 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
2409 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
2410 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
2411 suppresses the lines (same as <CODE>--no-location</CODE>).
2413 <DT><SAMP>‘--strict’</SAMP>
2415 <A NAME="IDX885"></A>
2416 Write out a strict Uniforum conforming PO file. Note that this
2417 Uniforum format should be avoided because it doesn't support the
2420 <DT><SAMP>‘-p’</SAMP>
2422 <DT><SAMP>‘--properties-output’</SAMP>
2424 <A NAME="IDX886"></A>
2425 <A NAME="IDX887"></A>
2426 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
2427 that this file format doesn't support plural forms and silently drops
2430 <DT><SAMP>‘--stringtable-output’</SAMP>
2432 <A NAME="IDX888"></A>
2433 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
2434 Note that this file format doesn't support plural forms.
2436 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
2438 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
2440 <A NAME="IDX889"></A>
2441 <A NAME="IDX890"></A>
2442 Set the output page width. Long strings in the output files will be
2443 split across multiple lines in order to ensure that each line's width
2444 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
2446 <DT><SAMP>‘--no-wrap’</SAMP>
2448 <A NAME="IDX891"></A>
2449 Do not break long message lines. Message lines whose width exceeds the
2450 output page width will not be split into several lines. Only file reference
2451 lines which are wider than the output page width will be split.
2453 <DT><SAMP>‘-s’</SAMP>
2455 <DT><SAMP>‘--sort-output’</SAMP>
2457 <A NAME="IDX892"></A>
2458 <A NAME="IDX893"></A>
2459 Generate sorted output. Note that using this option makes it much harder
2460 for the translator to understand each message's context.
2462 <DT><SAMP>‘-F’</SAMP>
2464 <DT><SAMP>‘--sort-by-file’</SAMP>
2466 <A NAME="IDX894"></A>
2467 <A NAME="IDX895"></A>
2468 Sort output by file location.
2474 <H3><A NAME="SEC138" HREF="gettext_toc.html#TOC138">9.8.7 Informative output</A></H3>
2478 <DT><SAMP>‘-h’</SAMP>
2480 <DT><SAMP>‘--help’</SAMP>
2482 <A NAME="IDX896"></A>
2483 <A NAME="IDX897"></A>
2484 Display this help and exit.
2486 <DT><SAMP>‘-V’</SAMP>
2488 <DT><SAMP>‘--version’</SAMP>
2490 <A NAME="IDX898"></A>
2491 <A NAME="IDX899"></A>
2492 Output version information and exit.
2498 <H2><A NAME="SEC139" HREF="gettext_toc.html#TOC139">9.9 Invoking the <CODE>msgen</CODE> Program</A></H2>
2501 <A NAME="IDX900"></A>
2502 <A NAME="IDX901"></A>
2505 msgen [<VAR>option</VAR>] <VAR>inputfile</VAR>
2509 <A NAME="IDX902"></A>
2510 The <CODE>msgen</CODE> program creates an English translation catalog. The
2511 input file is the last created English PO file, or a PO Template file
2512 (generally created by xgettext). Untranslated entries are assigned a
2513 translation that is identical to the msgid.
2517 Note: <SAMP>‘msginit --no-translator --locale=en’</SAMP> performs a very similar
2518 task. The main difference is that <CODE>msginit</CODE> cares specially about
2519 the header entry, whereas <CODE>msgen</CODE> doesn't.
2524 <H3><A NAME="SEC140" HREF="gettext_toc.html#TOC140">9.9.1 Input file location</A></H3>
2528 <DT><SAMP>‘<VAR>inputfile</VAR>’</SAMP>
2530 Input PO or POT file.
2532 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
2534 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
2536 <A NAME="IDX903"></A>
2537 <A NAME="IDX904"></A>
2538 Add <VAR>directory</VAR> to the list of directories. Source files are
2539 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
2540 file will be written relative to the current directory, though.
2545 If <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read.
2550 <H3><A NAME="SEC141" HREF="gettext_toc.html#TOC141">9.9.2 Output file location</A></H3>
2554 <DT><SAMP>‘-o <VAR>file</VAR>’</SAMP>
2556 <DT><SAMP>‘--output-file=<VAR>file</VAR>’</SAMP>
2558 <A NAME="IDX905"></A>
2559 <A NAME="IDX906"></A>
2560 Write output to specified file.
2565 The results are written to standard output if no output file is specified
2566 or if it is <SAMP>‘-’</SAMP>.
2571 <H3><A NAME="SEC142" HREF="gettext_toc.html#TOC142">9.9.3 Input file syntax</A></H3>
2575 <DT><SAMP>‘-P’</SAMP>
2577 <DT><SAMP>‘--properties-input’</SAMP>
2579 <A NAME="IDX907"></A>
2580 <A NAME="IDX908"></A>
2581 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
2582 syntax, not in PO file syntax.
2584 <DT><SAMP>‘--stringtable-input’</SAMP>
2586 <A NAME="IDX909"></A>
2587 Assume the input file is a NeXTstep/GNUstep localized resource file in
2588 <CODE>.strings</CODE> syntax, not in PO file syntax.
2594 <H3><A NAME="SEC143" HREF="gettext_toc.html#TOC143">9.9.4 Output details</A></H3>
2598 <DT><SAMP>‘--lang=<VAR>catalogname</VAR>’</SAMP>
2600 <A NAME="IDX910"></A>
2601 Specify the <SAMP>‘Language’</SAMP> field to be used in the header entry. See
2602 section <A HREF="gettext_6.html#SEC44">6.2 Filling in the Header Entry</A> for the meaning of this field. Note: The
2603 <SAMP>‘Language-Team’</SAMP> and <SAMP>‘Plural-Forms’</SAMP> fields are not set by this
2606 <DT><SAMP>‘--color’</SAMP>
2608 <DT><SAMP>‘--color=<VAR>when</VAR>’</SAMP>
2610 <A NAME="IDX911"></A>
2611 Specify whether or when to use colors and other text attributes.
2612 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
2614 <DT><SAMP>‘--style=<VAR>style_file</VAR>’</SAMP>
2616 <A NAME="IDX912"></A>
2617 Specify the CSS style rule file to use for <CODE>--color</CODE>.
2618 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
2620 <DT><SAMP>‘--force-po’</SAMP>
2622 <A NAME="IDX913"></A>
2623 Always write an output file even if it contains no message.
2625 <DT><SAMP>‘-i’</SAMP>
2627 <DT><SAMP>‘--indent’</SAMP>
2629 <A NAME="IDX914"></A>
2630 <A NAME="IDX915"></A>
2631 Write the .po file using indented style.
2633 <DT><SAMP>‘--no-location’</SAMP>
2635 <A NAME="IDX916"></A>
2636 Do not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines.
2638 <DT><SAMP>‘-n’</SAMP>
2640 <DT><SAMP>‘--add-location=<VAR>type</VAR>’</SAMP>
2642 <A NAME="IDX917"></A>
2643 Generate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default).
2645 The optional <VAR>type</VAR> can be either <SAMP>‘full’</SAMP>, <SAMP>‘file’</SAMP>, or
2646 <SAMP>‘never’</SAMP>. If it is not given or <SAMP>‘full’</SAMP>, it generates the
2647 lines with both file name and line number. If it is <SAMP>‘file’</SAMP>, the
2648 line number part is omitted. If it is <SAMP>‘never’</SAMP>, it completely
2649 suppresses the lines (same as <CODE>--no-location</CODE>).
2651 <DT><SAMP>‘--strict’</SAMP>
2653 <A NAME="IDX918"></A>
2654 Write out a strict Uniforum conforming PO file. Note that this
2655 Uniforum format should be avoided because it doesn't support the
2658 <DT><SAMP>‘-p’</SAMP>
2660 <DT><SAMP>‘--properties-output’</SAMP>
2662 <A NAME="IDX919"></A>
2663 <A NAME="IDX920"></A>
2664 Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note
2665 that this file format doesn't support plural forms and silently drops
2668 <DT><SAMP>‘--stringtable-output’</SAMP>
2670 <A NAME="IDX921"></A>
2671 Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax.
2672 Note that this file format doesn't support plural forms.
2674 <DT><SAMP>‘-w <VAR>number</VAR>’</SAMP>
2676 <DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP>
2678 <A NAME="IDX922"></A>
2679 <A NAME="IDX923"></A>
2680 Set the output page width. Long strings in the output files will be
2681 split across multiple lines in order to ensure that each line's width
2682 (= number of screen columns) is less or equal to the given <VAR>number</VAR>.
2684 <DT><SAMP>‘--no-wrap’</SAMP>
2686 <A NAME="IDX924"></A>
2687 Do not break long message lines. Message lines whose width exceeds the
2688 output page width will not be split into several lines. Only file reference
2689 lines which are wider than the output page width will be split.
2691 <DT><SAMP>‘-s’</SAMP>
2693 <DT><SAMP>‘--sort-output’</SAMP>
2695 <A NAME="IDX925"></A>
2696 <A NAME="IDX926"></A>
2697 Generate sorted output. Note that using this option makes it much harder
2698 for the translator to understand each message's context.
2700 <DT><SAMP>‘-F’</SAMP>
2702 <DT><SAMP>‘--sort-by-file’</SAMP>
2704 <A NAME="IDX927"></A>
2705 <A NAME="IDX928"></A>
2706 Sort output by file location.
2712 <H3><A NAME="SEC144" HREF="gettext_toc.html#TOC144">9.9.5 Informative output</A></H3>
2716 <DT><SAMP>‘-h’</SAMP>
2718 <DT><SAMP>‘--help’</SAMP>
2720 <A NAME="IDX929"></A>
2721 <A NAME="IDX930"></A>
2722 Display this help and exit.
2724 <DT><SAMP>‘-V’</SAMP>
2726 <DT><SAMP>‘--version’</SAMP>
2728 <A NAME="IDX931"></A>
2729 <A NAME="IDX932"></A>
2730 Output version information and exit.
2736 <H2><A NAME="SEC145" HREF="gettext_toc.html#TOC145">9.10 Invoking the <CODE>msgexec</CODE> Program</A></H2>
2739 <A NAME="IDX933"></A>
2740 <A NAME="IDX934"></A>
2743 msgexec [<VAR>option</VAR>] <VAR>command</VAR> [<VAR>command-option</VAR>]
2747 <A NAME="IDX935"></A>
2748 The <CODE>msgexec</CODE> program applies a command to all translations of a
2749 translation catalog.
2750 The <VAR>command</VAR> can be any program that reads a translation from standard
2751 input. It is invoked once for each translation. Its output becomes
2752 msgexec's output. <CODE>msgexec</CODE>'s return code is the maximum return code
2753 across all invocations.
2757 <A NAME="IDX936"></A>
2758 A special builtin command called <SAMP>‘0’</SAMP> outputs the translation, followed
2759 by a null byte. The output of <SAMP>‘msgexec 0’</SAMP> is suitable as input for
2760 <SAMP>‘xargs -0’</SAMP>.
2765 <DT><SAMP>‘--newline’</SAMP>
2767 <A NAME="IDX937"></A>
2768 Add newline at the end of each input line.
2773 <A NAME="IDX938"></A>
2774 <A NAME="IDX939"></A>
2775 <A NAME="IDX940"></A>
2776 <A NAME="IDX941"></A>
2777 <A NAME="IDX942"></A>
2778 <A NAME="IDX943"></A>
2779 <A NAME="IDX944"></A>
2780 <A NAME="IDX945"></A>
2781 During each <VAR>command</VAR> invocation, the environment variable
2782 <CODE>MSGEXEC_MSGID</CODE> is bound to the message's msgid, and the environment
2783 variable <CODE>MSGEXEC_LOCATION</CODE> is bound to the location in the PO file
2784 of the message. If the message has a context, the environment variable
2785 <CODE>MSGEXEC_MSGCTXT</CODE> is bound to the message's msgctxt, otherwise it is
2786 unbound. If the message has a plural form, environment variable
2787 <CODE>MSGEXEC_MSGID_PLURAL</CODE> is bound to the message's msgid_plural and
2788 <CODE>MSGEXEC_PLURAL_FORM</CODE> is bound to the order number of the plural
2789 actually processed (starting with 0), otherwise both are unbound.
2790 If the message has a previous msgid (added by <CODE>msgmerge</CODE>),
2791 environment variable <CODE>MSGEXEC_PREV_MSGCTXT</CODE> is bound to the
2792 message's previous msgctxt, <CODE>MSGEXEC_PREV_MSGID</CODE> is bound to
2793 the previous msgid, and <CODE>MSGEXEC_PREV_MSGID_PLURAL</CODE> is bound to
2794 the previous msgid_plural.
2798 <A NAME="IDX946"></A>
2799 Note: It is your responsibility to ensure that the <VAR>command</VAR> can cope
2800 with input encoded in the translation catalog's encoding. If the
2801 <VAR>command</VAR> wants input in a particular encoding, you can in a first step
2802 convert the translation catalog to that encoding using the <SAMP>‘msgconv’</SAMP>
2803 program, before invoking <SAMP>‘msgexec’</SAMP>. If the <VAR>command</VAR> wants input
2804 in the locale's encoding, but you want to avoid the locale's encoding, then
2805 you can first convert the translation catalog to UTF-8 using the
2806 <SAMP>‘msgconv’</SAMP> program and then make <SAMP>‘msgexec’</SAMP> work in an UTF-8
2807 locale, by using the <CODE>LC_ALL</CODE> environment variable.
2812 <H3><A NAME="SEC146" HREF="gettext_toc.html#TOC146">9.10.1 Input file location</A></H3>
2816 <DT><SAMP>‘-i <VAR>inputfile</VAR>’</SAMP>
2818 <DT><SAMP>‘--input=<VAR>inputfile</VAR>’</SAMP>
2820 <A NAME="IDX947"></A>
2821 <A NAME="IDX948"></A>
2824 <DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP>
2826 <DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP>
2828 <A NAME="IDX949"></A>
2829 <A NAME="IDX950"></A>
2830 Add <VAR>directory</VAR> to the list of directories. Source files are
2831 searched relative to this list of directories. The resulting <TT>‘.po’</TT>
2832 file will be written relative to the current directory, though.
2837 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
2842 <H3><A NAME="SEC147" HREF="gettext_toc.html#TOC147">9.10.2 Input file syntax</A></H3>
2846 <DT><SAMP>‘-P’</SAMP>
2848 <DT><SAMP>‘--properties-input’</SAMP>
2850 <A NAME="IDX951"></A>
2851 <A NAME="IDX952"></A>
2852 Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE>
2853 syntax, not in PO file syntax.
2855 <DT><SAMP>‘--stringtable-input’</SAMP>
2857 <A NAME="IDX953"></A>
2858 Assume the input file is a NeXTstep/GNUstep localized resource file in
2859 <CODE>.strings</CODE> syntax, not in PO file syntax.
2865 <H3><A NAME="SEC148" HREF="gettext_toc.html#TOC148">9.10.3 Informative output</A></H3>
2869 <DT><SAMP>‘-h’</SAMP>
2871 <DT><SAMP>‘--help’</SAMP>
2873 <A NAME="IDX954"></A>
2874 <A NAME="IDX955"></A>
2875 Display this help and exit.
2877 <DT><SAMP>‘-V’</SAMP>
2879 <DT><SAMP>‘--version’</SAMP>
2881 <A NAME="IDX956"></A>
2882 <A NAME="IDX957"></A>
2883 Output version information and exit.
2889 <H2><A NAME="SEC149" HREF="gettext_toc.html#TOC149">9.11 Highlighting parts of PO files</A></H2>
2892 Translators are usually only interested in seeing the untranslated and
2893 fuzzy messages of a PO file. Also, when a message is set fuzzy because
2894 the msgid changed, they want to see the differences between the previous
2895 msgid and the current one (especially if the msgid is long and only few
2896 words in it have changed). Finally, it's always welcome to highlight the
2897 different sections of a message in a PO file (comments, msgid, msgstr, etc.).
2901 Such highlighting is possible through the <CODE>msgcat</CODE> options
2902 <SAMP>‘--color’</SAMP> and <SAMP>‘--style’</SAMP>.
2908 <H3><A NAME="SEC150" HREF="gettext_toc.html#TOC150">9.11.1 The <CODE>--color</CODE> option</A></H3>
2911 <A NAME="IDX958"></A>
2912 The <SAMP>‘--color=<VAR>when</VAR>’</SAMP> option specifies under which conditions
2913 colorized output should be generated. The <VAR>when</VAR> part can be one of
2919 <DT><CODE>always</CODE>
2921 <DT><CODE>yes</CODE>
2923 The output will be colorized.
2925 <DT><CODE>never</CODE>
2929 The output will not be colorized.
2931 <DT><CODE>auto</CODE>
2933 <DT><CODE>tty</CODE>
2935 The output will be colorized if the output device is a tty, i.e. when the
2936 output goes directly to a text screen or terminal emulator window.
2938 <DT><CODE>html</CODE>
2940 The output will be colorized and be in HTML format.
2944 <SAMP>‘--color’</SAMP> is equivalent to <SAMP>‘--color=yes’</SAMP>. The default is
2945 <SAMP>‘--color=auto’</SAMP>.
2949 Thus, a command like <SAMP>‘msgcat vi.po’</SAMP> will produce colorized output
2950 when called by itself in a command window. Whereas in a pipe, such as
2951 <SAMP>‘msgcat vi.po | less -R’</SAMP>, it will not produce colorized output. To
2952 get colorized output in this situation nevertheless, use the command
2953 <SAMP>‘msgcat --color vi.po | less -R’</SAMP>.
2957 The <SAMP>‘--color=html’</SAMP> option will produce output that can be viewed in
2958 a browser. This can be useful, for example, for Indic languages,
2959 because the renderic of Indic scripts in browser is usually better than
2960 in terminal emulators.
2964 Note that the output produced with the <CODE>--color</CODE> option is <EM>not</EM>
2965 a valid PO file in itself. It contains additional terminal-specific escape
2966 sequences or HTML tags. A PO file reader will give a syntax error when
2967 confronted with such content. Except for the <SAMP>‘--color=html’</SAMP> case,
2968 you therefore normally don't need to save output produced with the
2969 <CODE>--color</CODE> option in a file.
2974 <H3><A NAME="SEC151" HREF="gettext_toc.html#TOC151">9.11.2 The environment variable <CODE>TERM</CODE></A></H3>
2977 <A NAME="IDX959"></A>
2978 The environment variable <CODE>TERM</CODE> contains a identifier for the text
2979 window's capabilities. You can get a detailed list of these cababilities
2980 by using the <SAMP>‘infocmp’</SAMP> command, using <SAMP>‘man 5 terminfo’</SAMP> as a
2985 When producing text with embedded color directives, <CODE>msgcat</CODE> looks
2986 at the <CODE>TERM</CODE> variable. Text windows today typically support at least
2987 8 colors. Often, however, the text window supports 16 or more colors,
2988 even though the <CODE>TERM</CODE> variable is set to a identifier denoting only
2989 8 supported colors. It can be worth setting the <CODE>TERM</CODE> variable to
2990 a different value in these cases:
2995 <DT><CODE>xterm</CODE>
2997 <CODE>xterm</CODE> is in most cases built with support for 16 colors. It can also
2998 be built with support for 88 or 256 colors (but not both). You can try to
2999 set <CODE>TERM</CODE> to either <CODE>xterm-16color</CODE>, <CODE>xterm-88color</CODE>, or
3000 <CODE>xterm-256color</CODE>.
3002 <DT><CODE>rxvt</CODE>
3004 <CODE>rxvt</CODE> is often built with support for 16 colors. You can try to set
3005 <CODE>TERM</CODE> to <CODE>rxvt-16color</CODE>.
3007 <DT><CODE>konsole</CODE>
3009 <CODE>konsole</CODE> too is often built with support for 16 colors. You can try to
3010 set <CODE>TERM</CODE> to <CODE>konsole-16color</CODE> or <CODE>xterm-16color</CODE>.
3014 After setting <CODE>TERM</CODE>, you can verify it by invoking
3015 <SAMP>‘msgcat --color=test’</SAMP> and seeing whether the output looks like a
3016 reasonable color map.
3021 <H3><A NAME="SEC152" HREF="gettext_toc.html#TOC152">9.11.3 The <CODE>--style</CODE> option</A></H3>
3024 <A NAME="IDX960"></A>
3025 The <SAMP>‘--style=<VAR>style_file</VAR>’</SAMP> option specifies the style file to use
3026 when colorizing. It has an effect only when the <CODE>--color</CODE> option is
3031 <A NAME="IDX961"></A>
3032 If the <CODE>--style</CODE> option is not specified, the environment variable
3033 <CODE>PO_STYLE</CODE> is considered. It is meant to point to the user's
3034 preferred style for PO files.
3038 The default style file is <TT>‘$prefix/share/gettext/styles/po-default.css’</TT>,
3039 where <CODE>$prefix</CODE> is the installation location.
3043 A few style files are predefined:
3046 <DT><TT>‘po-vim.css’</TT>
3048 This style imitates the look used by vim 7.
3050 <DT><TT>‘po-emacs-x.css’</TT>
3052 This style imitates the look used by GNU Emacs 21 and 22 in an X11 window.
3054 <DT><TT>‘po-emacs-xterm.css’</TT>
3056 <DT><TT>‘po-emacs-xterm16.css’</TT>
3058 <DT><TT>‘po-emacs-xterm256.css’</TT>
3060 This style imitates the look used by GNU Emacs 22 in a terminal of type
3061 <SAMP>‘xterm’</SAMP> (8 colors) or <SAMP>‘xterm-16color’</SAMP> (16 colors) or
3062 <SAMP>‘xterm-256color’</SAMP> (256 colors), respectively.
3066 You can use these styles without specifying a directory. They are actually
3067 located in <TT>‘$prefix/share/gettext/styles/’</TT>, where <CODE>$prefix</CODE> is the
3068 installation location.
3072 You can also design your own styles. This is described in the next section.
3078 <H3><A NAME="SEC153" HREF="gettext_toc.html#TOC153">9.11.4 Style rules for PO files</A></H3>
3081 The same style file can be used for styling of a PO file, for terminal
3082 output and for HTML output. It is written in CSS (Cascading Style Sheet)
3083 syntax. See <A HREF="http://www.w3.org/TR/css2/cover.html">http://www.w3.org/TR/css2/cover.html</A> for a formal
3084 definition of CSS. Many HTML authoring tutorials also contain explanations
3089 In the case of HTML output, the style file is embedded in the HTML output.
3090 In the case of text output, the style file is interpreted by the
3091 <CODE>msgcat</CODE> program. This means, in particular, that when
3092 <CODE>@import</CODE> is used with relative file names, the file names are
3099 relative to the resulting HTML file, in the case of HTML output,
3103 relative to the style sheet containing the <CODE>@import</CODE>, in the case of
3104 text output. (Actually, <CODE>@import</CODE>s are not yet supported in this case,
3105 due to a limitation in <CODE>libcroco</CODE>.)
3109 CSS rules are built up from selectors and declarations. The declarations
3110 specify graphical properties; the selectors specify specify when they apply.
3114 In PO files, the following simple selectors (based on "CSS classes", see
3115 the CSS2 spec, section 5.8.3) are supported.
3122 Selectors that apply to entire messages:
3126 <DT><CODE>.header</CODE>
3128 This matches the header entry of a PO file.
3130 <DT><CODE>.translated</CODE>
3132 This matches a translated message.
3134 <DT><CODE>.untranslated</CODE>
3136 This matches an untranslated message (i.e. a message with empty translation).
3138 <DT><CODE>.fuzzy</CODE>
3140 This matches a fuzzy message (i.e. a message which has a translation that
3141 needs review by the translator).
3143 <DT><CODE>.obsolete</CODE>
3145 This matches an obsolete message (i.e. a message that was translated but is
3146 not needed by the current POT file any more).
3151 Selectors that apply to parts of a message in PO syntax. Recall the general
3152 structure of a message in PO syntax:
3156 <VAR>white-space</VAR>
3157 # <VAR>translator-comments</VAR>
3158 #. <VAR>extracted-comments</VAR>
3159 #: <VAR>reference</VAR>...
3160 #, <VAR>flag</VAR>...
3161 #| msgid <VAR>previous-untranslated-string</VAR>
3162 msgid <VAR>untranslated-string</VAR>
3163 msgstr <VAR>translated-string</VAR>
3168 <DT><CODE>.comment</CODE>
3170 This matches all comments (translator comments, extracted comments,
3171 source file reference comments, flag comments, previous message comments,
3172 as well as the entire obsolete messages).
3174 <DT><CODE>.translator-comment</CODE>
3176 This matches the translator comments.
3178 <DT><CODE>.extracted-comment</CODE>
3180 This matches the extracted comments, i.e. the comments placed by the
3181 programmer at the attention of the translator.
3183 <DT><CODE>.reference-comment</CODE>
3185 This matches the source file reference comments (entire lines).
3187 <DT><CODE>.reference</CODE>
3189 This matches the individual source file references inside the source file
3190 reference comment lines.
3192 <DT><CODE>.flag-comment</CODE>
3194 This matches the flag comment lines (entire lines).
3196 <DT><CODE>.flag</CODE>
3198 This matches the individual flags inside flag comment lines.
3200 <DT><CODE>.fuzzy-flag</CODE>
3202 This matches the `fuzzy' flag inside flag comment lines.
3204 <DT><CODE>.previous-comment</CODE>
3206 This matches the comments containing the previous untranslated string (entire
3209 <DT><CODE>.previous</CODE>
3211 This matches the previous untranslated string including the string delimiters,
3212 the associated keywords (<CODE>msgid</CODE> etc.) and the spaces between them.
3214 <DT><CODE>.msgid</CODE>
3216 This matches the untranslated string including the string delimiters,
3217 the associated keywords (<CODE>msgid</CODE> etc.) and the spaces between them.
3219 <DT><CODE>.msgstr</CODE>
3221 This matches the translated string including the string delimiters,
3222 the associated keywords (<CODE>msgstr</CODE> etc.) and the spaces between them.
3224 <DT><CODE>.keyword</CODE>
3226 This matches the keywords (<CODE>msgid</CODE>, <CODE>msgstr</CODE>, etc.).
3228 <DT><CODE>.string</CODE>
3230 This matches strings, including the string delimiters (double quotes).
3235 Selectors that apply to parts of strings:
3239 <DT><CODE>.text</CODE>
3241 This matches the entire contents of a string (excluding the string delimiters,
3242 i.e. the double quotes).
3244 <DT><CODE>.escape-sequence</CODE>
3246 This matches an escape sequence (starting with a backslash).
3248 <DT><CODE>.format-directive</CODE>
3250 This matches a format string directive (starting with a <SAMP>‘%’</SAMP> sign in the
3251 case of most programming languages, with a <SAMP>‘{’</SAMP> in the case of
3252 <CODE>java-format</CODE> and <CODE>csharp-format</CODE>, with a <SAMP>‘~’</SAMP> in the case of
3253 <CODE>lisp-format</CODE> and <CODE>scheme-format</CODE>, or with <SAMP>‘$’</SAMP> in the case of
3254 <CODE>sh-format</CODE>).
3256 <DT><CODE>.invalid-format-directive</CODE>
3258 This matches an invalid format string directive.
3260 <DT><CODE>.added</CODE>
3262 In an untranslated string, this matches a part of the string that was not
3263 present in the previous untranslated string. (Not yet implemented in this
3266 <DT><CODE>.changed</CODE>
3268 In an untranslated string or in a previous untranslated string, this matches
3269 a part of the string that is changed or replaced. (Not yet implemented in
3272 <DT><CODE>.removed</CODE>
3274 In a previous untranslated string, this matches a part of the string that
3275 is not present in the current untranslated string. (Not yet implemented in
3281 These selectors can be combined to hierarchical selectors. For example,
3286 .msgstr .invalid-format-directive { color: red; }
3290 will highlight the invalid format directives in the translated strings.
3294 In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements
3295 (CSS2 spec, section 5.12) are not supported.
3299 The declarations in HTML mode are not limited; any graphical attribute
3300 supported by the browsers can be used.
3304 The declarations in text mode are limited to the following properties. Other
3305 properties will be silently ignored.
3310 <DT><CODE>color</CODE> (CSS2 spec, section 14.1)
3312 <DT><CODE>background-color</CODE> (CSS2 spec, section 14.2.1)
3314 These properties is supported. Colors will be adjusted to match the terminal's
3315 capabilities. Note that many terminals support only 8 colors.
3317 <DT><CODE>font-weight</CODE> (CSS2 spec, section 15.2.3)
3319 This property is supported, but most terminals can only render two different
3320 weights: <CODE>normal</CODE> and <CODE>bold</CODE>. Values >= 600 are rendered as
3323 <DT><CODE>font-style</CODE> (CSS2 spec, section 15.2.3)
3325 This property is supported. The values <CODE>italic</CODE> and <CODE>oblique</CODE> are
3326 rendered the same way.
3328 <DT><CODE>text-decoration</CODE> (CSS2 spec, section 16.3.1)
3330 This property is supported, limited to the values <CODE>none</CODE> and
3331 <CODE>underline</CODE>.
3336 <H3><A NAME="SEC154" HREF="gettext_toc.html#TOC154">9.11.5 Customizing <CODE>less</CODE> for viewing PO files</A></H3>
3339 The <SAMP>‘less’</SAMP> program is a popular text file browser for use in a text
3340 screen or terminal emulator. It also supports text with embedded escape
3341 sequences for colors and text decorations.
3345 You can use <CODE>less</CODE> to view a PO file like this (assuming an UTF-8
3351 msgcat --to-code=UTF-8 --color xyz.po | less -R
3355 You can simplify this to this simple command:
3364 after these three preparations:
3371 Add the options <SAMP>‘-R’</SAMP> and <SAMP>‘-f’</SAMP> to the <CODE>LESS</CODE> environment
3372 variable. In sh shells:
3375 $ LESS="$LESS -R -f"
3381 If your system does not already have the <TT>‘lessopen.sh’</TT> and
3382 <TT>‘lessclose.sh’</TT> scripts, create them and set the <CODE>LESSOPEN</CODE> and
3383 <CODE>LESSCLOSE</CODE> environment variables, as indicated in the manual page
3384 (<SAMP>‘man less’</SAMP>).
3388 Add to <TT>‘lessopen.sh’</TT> a piece of script that recognizes PO files
3389 through their file extension and invokes <CODE>msgcat</CODE> on them, producing
3390 a temporary file. Like this:
3396 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"`
3397 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile"
3408 <H2><A NAME="SEC155" HREF="gettext_toc.html#TOC155">9.12 Writing your own programs that process PO files</A></H2>
3411 For the tasks for which a combination of <SAMP>‘msgattrib’</SAMP>, <SAMP>‘msgcat’</SAMP> etc.
3412 is not sufficient, a set of C functions is provided in a library, to make it
3413 possible to process PO files in your own programs. When you use this library,
3414 you don't need to write routines to parse the PO file; instead, you retrieve
3415 a pointer in memory to each of messages contained in the PO file. Functions
3416 for writing PO files are not provided at this time.
3420 The functions are declared in the header file <SAMP>‘<gettext-po.h>’</SAMP>, and are
3421 defined in a library called <SAMP>‘libgettextpo’</SAMP>.
3426 <DT><U>Data Type:</U> <B>po_file_t</B>
3427 <DD><A NAME="IDX962"></A>
3428 This is a pointer type that refers to the contents of a PO file, after it has
3429 been read into memory.
3435 <DT><U>Data Type:</U> <B>po_message_iterator_t</B>
3436 <DD><A NAME="IDX963"></A>
3437 This is a pointer type that refers to an iterator that produces a sequence of
3444 <DT><U>Data Type:</U> <B>po_message_t</B>
3445 <DD><A NAME="IDX964"></A>
3446 This is a pointer type that refers to a message of a PO file, including its
3453 <DT><U>Function:</U> po_file_t <B>po_file_read</B> <I>(const char *<VAR>filename</VAR>)</I>
3454 <DD><A NAME="IDX965"></A>
3455 The <CODE>po_file_read</CODE> function reads a PO file into memory. The file name
3456 is given as argument. The return value is a handle to the PO file's contents,
3457 valid until <CODE>po_file_free</CODE> is called on it. In case of error, the return
3458 value is <CODE>NULL</CODE>, and <CODE>errno</CODE> is set.
3464 <DT><U>Function:</U> void <B>po_file_free</B> <I>(po_file_t <VAR>file</VAR>)</I>
3465 <DD><A NAME="IDX966"></A>
3466 The <CODE>po_file_free</CODE> function frees a PO file's contents from memory,
3467 including all messages that are only implicitly accessible through iterators.
3473 <DT><U>Function:</U> const char * const * <B>po_file_domains</B> <I>(po_file_t <VAR>file</VAR>)</I>
3474 <DD><A NAME="IDX967"></A>
3475 The <CODE>po_file_domains</CODE> function returns the domains for which the given
3476 PO file has messages. The return value is a <CODE>NULL</CODE> terminated array
3477 which is valid as long as the <VAR>file</VAR> handle is valid. For PO files which
3478 contain no <SAMP>‘domain’</SAMP> directive, the return value contains only one domain,
3479 namely the default domain <CODE>"messages"</CODE>.
3485 <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>
3486 <DD><A NAME="IDX968"></A>
3487 The <CODE>po_message_iterator</CODE> returns an iterator that will produce the
3488 messages of <VAR>file</VAR> that belong to the given <VAR>domain</VAR>. If <VAR>domain</VAR>
3489 is <CODE>NULL</CODE>, the default domain is used instead. To list the messages,
3490 use the function <CODE>po_next_message</CODE> repeatedly.
3496 <DT><U>Function:</U> void <B>po_message_iterator_free</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I>
3497 <DD><A NAME="IDX969"></A>
3498 The <CODE>po_message_iterator_free</CODE> function frees an iterator previously
3499 allocated through the <CODE>po_message_iterator</CODE> function.
3505 <DT><U>Function:</U> po_message_t <B>po_next_message</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I>
3506 <DD><A NAME="IDX970"></A>
3507 The <CODE>po_next_message</CODE> function returns the next message from
3508 <VAR>iterator</VAR> and advances the iterator. It returns <CODE>NULL</CODE> when the
3509 iterator has reached the end of its message list.
3514 The following functions returns details of a <CODE>po_message_t</CODE>. Recall
3515 that the results are valid as long as the <VAR>file</VAR> handle is valid.
3520 <DT><U>Function:</U> const char * <B>po_message_msgid</B> <I>(po_message_t <VAR>message</VAR>)</I>
3521 <DD><A NAME="IDX971"></A>
3522 The <CODE>po_message_msgid</CODE> function returns the <CODE>msgid</CODE> (untranslated
3523 English string) of a message. This is guaranteed to be non-<CODE>NULL</CODE>.
3529 <DT><U>Function:</U> const char * <B>po_message_msgid_plural</B> <I>(po_message_t <VAR>message</VAR>)</I>
3530 <DD><A NAME="IDX972"></A>
3531 The <CODE>po_message_msgid_plural</CODE> function returns the <CODE>msgid_plural</CODE>
3532 (untranslated English plural string) of a message with plurals, or <CODE>NULL</CODE>
3533 for a message without plural.
3539 <DT><U>Function:</U> const char * <B>po_message_msgstr</B> <I>(po_message_t <VAR>message</VAR>)</I>
3540 <DD><A NAME="IDX973"></A>
3541 The <CODE>po_message_msgstr</CODE> function returns the <CODE>msgstr</CODE> (translation)
3542 of a message. For an untranslated message, the return value is an empty
3549 <DT><U>Function:</U> const char * <B>po_message_msgstr_plural</B> <I>(po_message_t <VAR>message</VAR>, int <VAR>index</VAR>)</I>
3550 <DD><A NAME="IDX974"></A>
3551 The <CODE>po_message_msgstr_plural</CODE> function returns the
3552 <CODE>msgstr[<VAR>index</VAR>]</CODE> of a message with plurals, or <CODE>NULL</CODE> when
3553 the <VAR>index</VAR> is out of range or for a message without plural.
3558 Here is an example code how these functions can be used.
3563 const char *filename = ...;
3564 po_file_t file = po_file_read (filename);
3567 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
3569 const char * const *domains = po_file_domains (file);
3570 const char * const *domainp;
3572 for (domainp = domains; *domainp; domainp++)
3574 const char *domain = *domainp;
3575 po_message_iterator_t iterator = po_message_iterator (file, domain);
3579 po_message_t *message = po_next_message (iterator);
3581 if (message == NULL)
3584 const char *msgid = po_message_msgid (message);
3585 const char *msgstr = po_message_msgstr (message);
3590 po_message_iterator_free (iterator);
3593 po_file_free (file);
3597 Go 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>.
projects / platform / upstream / gettext.git / blob