| blob | 536a39e586316b18af57b0ee8b59c6be04450a1a |
1 <HTML>
2 <HEAD>
3 <!-- This HTML file has been created by texi2html 1.52b
4 from gettext.texi on 6 June 2010 -->
8 </HEAD>
9 <BODY>
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>.
11 <P><HR><P>
15 <P>
18 </P>
19 <P>
20 Sometimes it is necessary to manipulate PO files in a way that is better
22 complete set of tools for this purpose.
24 </P>
25 <P>
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
32 possible conflicts that arose during the merge.
34 </P>
35 <P>
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
42 </P>
43 <P>
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
50 </P>
51 <P>
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
60 </P>
61 <P>
63 which a given PO file was made. This can be done through a filter command
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.
68 </P>
69 <P>
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
75 </P>
76 <P>
78 When third party tools create PO or POT files, sometimes duplicates cannot
80 encounter duplicate msgids in the same file and in the same domain.
83 </P>
84 <P>
86 duplicates, occurring in different files.
88 </P>
89 <P>
91 completely translated.
93 </P>
94 <P>
97 or untranslated messages of a translation catalog.
99 </P>
100 <P>
102 catalogs. It copies each message's msgid to its msgstr.
104 </P>
105 <P>
106 Finally, for those applications where all these various programs are not
108 write other specialized programs that process PO files.
110 </P>
114 <H2><A NAME="SEC80" HREF="gettext_toc.html#TOC80">9.1 Invoking the <CODE>msgcat</CODE> Program</A></H2>
116 <P>
120 <PRE>
122 </PRE>
124 <P>
128 It finds messages which are common to two or more of the specified PO files.
131 used to specify less commonality before messages are printed (i.e.
133 comments and extract comments will be cumulated, except that if
135 to define them. File positions from all PO files will be cumulated.
137 </P>
145 <DD>
146 Input files.
149 <DD>
151 <DD>
155 them from the command line.
158 <DD>
160 <DD>
165 file will be written relative to the current directory, though.
167 </DL>
169 <P>
172 </P>
180 <DD>
182 <DD>
185 Write output to specified file.
187 </DL>
189 <P>
191 The results are written to standard output if no output file is specified
194 </P>
202 <DD>
204 <DD>
208 if not set.
211 <DD>
213 <DD>
217 set.
220 <DD>
222 <DD>
226 printed.
228 </DL>
237 <DD>
239 <DD>
243 syntax, not in PO file syntax.
246 <DD>
248 Assume the input files are NeXTstep/GNUstep localized resource files in
251 </DL>
260 <DD>
262 <DD>
265 Specify encoding for output.
268 <DD>
270 Use first available translation for each message. Don't merge several
271 translations into one.
274 <DD>
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.
281 <DD>
283 <DD>
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.
289 <DD>
292 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
295 <DD>
297 Always write an output file even if it contains no message.
300 <DD>
302 <DD>
305 Write the .po file using indented style.
308 <DD>
313 <DD>
315 <DD>
321 <DD>
323 Write out a strict Uniforum conforming PO file. Note that this
324 Uniforum format should be avoided because it doesn't support the
325 GNU extensions.
328 <DD>
330 <DD>
334 that this file format doesn't support plural forms and silently drops
335 obsolete messages.
338 <DD>
341 Note that this file format doesn't support plural forms.
344 <DD>
346 <DD>
349 Set the output page width. Long strings in the output files will be
350 split across multiple lines in order to ensure that each line's width
354 <DD>
356 Do not break long message lines. Message lines whose width exceeds the
357 output page width will not be split into several lines. Only file reference
358 lines which are wider than the output page width will be split.
361 <DD>
363 <DD>
367 Generate sorted output. Note that using this option makes it much harder
368 for the translator to understand each message's context.
371 <DD>
373 <DD>
376 Sort output by file location.
378 </DL>
387 <DD>
389 <DD>
392 Display this help and exit.
395 <DD>
397 <DD>
400 Output version information and exit.
402 </DL>
406 <H2><A NAME="SEC87" HREF="gettext_toc.html#TOC87">9.2 Invoking the <CODE>msgconv</CODE> Program</A></H2>
408 <P>
412 <PRE>
414 </PRE>
416 <P>
419 character encoding.
421 </P>
429 <DD>
430 Input PO file.
433 <DD>
435 <DD>
440 file will be written relative to the current directory, though.
442 </DL>
444 <P>
445 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
447 </P>
455 <DD>
457 <DD>
460 Write output to specified file.
462 </DL>
464 <P>
465 The results are written to standard output if no output file is specified
468 </P>
476 <DD>
478 <DD>
481 Specify encoding for output.
483 </DL>
485 <P>
486 The default encoding is the current locale's encoding.
488 </P>
496 <DD>
498 <DD>
502 syntax, not in PO file syntax.
505 <DD>
507 Assume the input file is a NeXTstep/GNUstep localized resource file in
510 </DL>
519 <DD>
521 <DD>
523 Specify whether or when to use colors and other text attributes.
524 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
527 <DD>
530 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
533 <DD>
535 Always write an output file even if it contains no message.
538 <DD>
540 <DD>
543 Write the .po file using indented style.
546 <DD>
551 <DD>
556 <DD>
558 Write out a strict Uniforum conforming PO file. Note that this
559 Uniforum format should be avoided because it doesn't support the
560 GNU extensions.
563 <DD>
565 <DD>
569 that this file format doesn't support plural forms and silently drops
570 obsolete messages.
573 <DD>
576 Note that this file format doesn't support plural forms.
579 <DD>
581 <DD>
584 Set the output page width. Long strings in the output files will be
585 split across multiple lines in order to ensure that each line's width
589 <DD>
591 Do not break long message lines. Message lines whose width exceeds the
592 output page width will not be split into several lines. Only file reference
593 lines which are wider than the output page width will be split.
596 <DD>
598 <DD>
601 Generate sorted output. Note that using this option makes it much harder
602 for the translator to understand each message's context.
605 <DD>
607 <DD>
610 Sort output by file location.
612 </DL>
621 <DD>
623 <DD>
626 Display this help and exit.
629 <DD>
631 <DD>
634 Output version information and exit.
636 </DL>
640 <H2><A NAME="SEC94" HREF="gettext_toc.html#TOC94">9.3 Invoking the <CODE>msggrep</CODE> Program</A></H2>
642 <P>
646 <PRE>
648 </PRE>
650 <P>
653 that match a given pattern or belong to some given source files.
655 </P>
663 <DD>
664 Input PO file.
667 <DD>
669 <DD>
674 file will be written relative to the current directory, though.
676 </DL>
678 <P>
679 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
681 </P>
689 <DD>
691 <DD>
694 Write output to specified file.
696 </DL>
698 <P>
699 The results are written to standard output if no output file is specified
702 </P>
708 <PRE>
712 </PRE>
714 <P>
715 A message is selected if
717 <UL>
718 <LI>it comes from one of the specified source files,
720 <LI>or if it comes from one of the specified domains,
734 </UL>
736 <P>
737 When more than one selection criterion is specified, the set of selected
738 messages is the union of the selected messages of each criterion.
740 </P>
741 <P>
744 <PRE>
746 </PRE>
748 <P>
750 expressions if -E is given, or fixed strings if -F is given.
752 </P>
756 <DD>
758 <DD>
762 either a literal file name or a wildcard pattern.
765 <DD>
767 <DD>
773 <DD>
775 <DD>
778 Start of patterns for the msgctxt.
781 <DD>
783 <DD>
786 Start of patterns for the msgid.
789 <DD>
791 <DD>
794 Start of patterns for the msgstr.
797 <DD>
799 <DD>
802 Start of patterns for the translator's comment.
805 <DD>
807 <DD>
810 Start of patterns for the extracted comments.
813 <DD>
815 <DD>
821 <DD>
823 <DD>
829 <DD>
831 <DD>
837 <DD>
839 <DD>
845 <DD>
847 <DD>
850 Ignore case distinctions.
853 <DD>
855 <DD>
858 Output only the messages that do not match any selection criterion, instead
859 of the messages that match a selection criterion.
861 </DL>
870 <DD>
872 <DD>
876 syntax, not in PO file syntax.
879 <DD>
881 Assume the input file is a NeXTstep/GNUstep localized resource file in
884 </DL>
893 <DD>
895 <DD>
897 Specify whether or when to use colors and other text attributes.
898 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
901 <DD>
904 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
907 <DD>
909 Always write an output file even if it contains no message.
912 <DD>
914 Write the .po file using indented style.
917 <DD>
922 <DD>
927 <DD>
929 Write out a strict Uniforum conforming PO file. Note that this
930 Uniforum format should be avoided because it doesn't support the
931 GNU extensions.
934 <DD>
936 <DD>
940 that this file format doesn't support plural forms and silently drops
941 obsolete messages.
944 <DD>
947 Note that this file format doesn't support plural forms.
950 <DD>
952 <DD>
955 Set the output page width. Long strings in the output files will be
956 split across multiple lines in order to ensure that each line's width
960 <DD>
962 Do not break long message lines. Message lines whose width exceeds the
963 output page width will not be split into several lines. Only file reference
964 lines which are wider than the output page width will be split.
967 <DD>
969 Generate sorted output. Note that using this option makes it much harder
970 for the translator to understand each message's context.
973 <DD>
975 Sort output by file location.
977 </DL>
986 <DD>
988 <DD>
991 Display this help and exit.
994 <DD>
996 <DD>
999 Output version information and exit.
1001 </DL>
1007 <P>
1008 To extract the messages that come from the source files
1011 </P>
1013 <PRE>
1014 msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po
1015 </PRE>
1017 <P>
1018 To extract the messages that contain the string “Please specify” in the
1019 original string:
1021 </P>
1023 <PRE>
1024 msggrep --msgid -F -e 'Please specify' input.po
1025 </PRE>
1027 <P>
1028 To extract the messages that have a context specifier of either “Menu>File”
1029 or “Menu>Edit” or a submenu of them:
1031 </P>
1033 <PRE>
1034 msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po
1035 </PRE>
1037 <P>
1038 To extract the messages whose translation contains one of the strings in the
1041 </P>
1043 <PRE>
1044 msggrep --msgstr -F -f wordlist.txt input.po
1045 </PRE>
1049 <H2><A NAME="SEC102" HREF="gettext_toc.html#TOC102">9.4 Invoking the <CODE>msgfilter</CODE> Program</A></H2>
1051 <P>
1055 <PRE>
1057 </PRE>
1059 <P>
1062 translation catalog.
1064 </P>
1065 <P>
1072 of the message. If the message has a context, the environment variable
1074 unbound.
1076 </P>
1084 <DD>
1086 <DD>
1089 Input PO file.
1092 <DD>
1094 <DD>
1099 file will be written relative to the current directory, though.
1101 </DL>
1103 <P>
1104 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
1106 </P>
1114 <DD>
1116 <DD>
1119 Write output to specified file.
1121 </DL>
1123 <P>
1124 The results are written to standard output if no output file is specified
1127 </P>
1132 <P>
1134 input and writes a modified translation to standard output. A frequently
1136 recognized.
1138 </P>
1139 <P>
1141 Note: If the filter is not a built-in filter, you have to care about encodings:
1143 with input encoded in the translation catalog's encoding. If the
1146 program, before invoking <SAMP>‘msgfilter’</SAMP>. If the <VAR>filter</VAR> wants input
1147 in the locale's encoding, but you want to avoid the locale's encoding, then
1148 you can first convert the translation catalog to UTF-8 using the
1149 <SAMP>‘msgconv’</SAMP> program and then make <SAMP>‘msgfilter’</SAMP> work in an UTF-8
1152 </P>
1153 <P>
1155 Note: Most translations in a translation catalog don't end with a newline
1157 recognizes its last input line even if it ends without a newline, and that
1159 program on some platforms is known to ignore the last line of input if it
1161 does not have this limitation.
1163 </P>
1166 <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>
1171 <DD>
1173 <DD>
1179 <DD>
1181 <DD>
1187 <DD>
1189 <DD>
1191 <DD>
1195 Suppress automatic printing of pattern space.
1197 </DL>
1203 <P>
1208 Cyrillic script, to the Latin script.
1209 The command <SAMP>‘msgfilter recode-sr-latin’</SAMP> applies this conversion to the
1213 </P>
1214 <P>
1215 The use of built-in filters is not sensitive to the current locale's encoding.
1216 Moreover, when used with a built-in filter, <SAMP>‘msgfilter’</SAMP> can automatically
1217 convert the message catalog to the UTF-8 encoding when needed.
1219 </P>
1227 <DD>
1229 <DD>
1233 syntax, not in PO file syntax.
1236 <DD>
1238 Assume the input file is a NeXTstep/GNUstep localized resource file in
1241 </DL>
1250 <DD>
1252 <DD>
1254 Specify whether or when to use colors and other text attributes.
1255 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
1258 <DD>
1261 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
1264 <DD>
1266 Always write an output file even if it contains no message.
1269 <DD>
1271 Write the .po file using indented style.
1274 <DD>
1277 instead of filtering it. By default, the header entry is subject to
1278 filtering like any other message.
1281 <DD>
1286 <DD>
1291 <DD>
1293 Write out a strict Uniforum conforming PO file. Note that this
1294 Uniforum format should be avoided because it doesn't support the
1295 GNU extensions.
1298 <DD>
1300 <DD>
1304 that this file format doesn't support plural forms and silently drops
1305 obsolete messages.
1308 <DD>
1311 Note that this file format doesn't support plural forms.
1314 <DD>
1316 <DD>
1319 Set the output page width. Long strings in the output files will be
1320 split across multiple lines in order to ensure that each line's width
1324 <DD>
1326 Do not break long message lines. Message lines whose width exceeds the
1327 output page width will not be split into several lines. Only file reference
1328 lines which are wider than the output page width will be split.
1331 <DD>
1333 <DD>
1336 Generate sorted output. Note that using this option makes it much harder
1337 for the translator to understand each message's context.
1340 <DD>
1342 <DD>
1345 Sort output by file location.
1347 </DL>
1356 <DD>
1358 <DD>
1361 Display this help and exit.
1364 <DD>
1366 <DD>
1369 Output version information and exit.
1371 </DL>
1377 <P>
1378 To convert German translations to Swiss orthography (in an UTF-8 locale):
1380 </P>
1382 <PRE>
1384 </PRE>
1386 <P>
1387 To convert Serbian translations in Cyrillic script to Latin script:
1389 </P>
1391 <PRE>
1392 msgfilter recode-sr-latin < sr.po
1393 </PRE>
1397 <H2><A NAME="SEC112" HREF="gettext_toc.html#TOC112">9.5 Invoking the <CODE>msguniq</CODE> Program</A></H2>
1399 <P>
1403 <PRE>
1405 </PRE>
1407 <P>
1411 catalog. It finds duplicate translations of the same message ID. Such
1415 output, and all other messages are discarded. Comments and extracted
1417 specified, they will be taken from the first translation. File positions
1419 discarded.
1421 </P>
1429 <DD>
1430 Input PO file.
1433 <DD>
1435 <DD>
1440 file will be written relative to the current directory, though.
1442 </DL>
1444 <P>
1445 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
1447 </P>
1455 <DD>
1457 <DD>
1460 Write output to specified file.
1462 </DL>
1464 <P>
1465 The results are written to standard output if no output file is specified
1468 </P>
1476 <DD>
1478 <DD>
1481 Print only duplicates.
1484 <DD>
1486 <DD>
1489 Print only unique messages, discard duplicates.
1491 </DL>
1500 <DD>
1502 <DD>
1506 syntax, not in PO file syntax.
1509 <DD>
1511 Assume the input file is a NeXTstep/GNUstep localized resource file in
1514 </DL>
1523 <DD>
1525 <DD>
1528 Specify encoding for output.
1531 <DD>
1533 Use first available translation for each message. Don't merge several
1534 translations into one.
1537 <DD>
1539 <DD>
1541 Specify whether or when to use colors and other text attributes.
1542 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
1545 <DD>
1548 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
1551 <DD>
1553 Always write an output file even if it contains no message.
1556 <DD>
1558 <DD>
1561 Write the .po file using indented style.
1564 <DD>
1569 <DD>
1571 <DD>
1577 <DD>
1579 Write out a strict Uniforum conforming PO file. Note that this
1580 Uniforum format should be avoided because it doesn't support the
1581 GNU extensions.
1584 <DD>
1586 <DD>
1590 that this file format doesn't support plural forms and silently drops
1591 obsolete messages.
1594 <DD>
1597 Note that this file format doesn't support plural forms.
1600 <DD>
1602 <DD>
1605 Set the output page width. Long strings in the output files will be
1606 split across multiple lines in order to ensure that each line's width
1610 <DD>
1612 Do not break long message lines. Message lines whose width exceeds the
1613 output page width will not be split into several lines. Only file reference
1614 lines which are wider than the output page width will be split.
1617 <DD>
1619 <DD>
1622 Generate sorted output. Note that using this option makes it much harder
1623 for the translator to understand each message's context.
1626 <DD>
1628 <DD>
1631 Sort output by file location.
1633 </DL>
1642 <DD>
1644 <DD>
1647 Display this help and exit.
1650 <DD>
1652 <DD>
1655 Output version information and exit.
1657 </DL>
1661 <H2><A NAME="SEC119" HREF="gettext_toc.html#TOC119">9.6 Invoking the <CODE>msgcomm</CODE> Program</A></H2>
1663 <P>
1667 <PRE>
1669 </PRE>
1671 <P>
1674 of the specified PO files.
1677 used to specify less commonality before messages are printed (i.e.
1679 comments and extract comments will be preserved, but only from the first
1680 PO file to define them. File positions from all PO files will be
1681 cumulated.
1683 </P>
1691 <DD>
1692 Input files.
1695 <DD>
1697 <DD>
1701 them from the command line.
1704 <DD>
1706 <DD>
1711 file will be written relative to the current directory, though.
1713 </DL>
1715 <P>
1718 </P>
1726 <DD>
1728 <DD>
1731 Write output to specified file.
1733 </DL>
1735 <P>
1736 The results are written to standard output if no output file is specified
1739 </P>
1747 <DD>
1749 <DD>
1753 if not set.
1756 <DD>
1758 <DD>
1762 set.
1765 <DD>
1767 <DD>
1771 printed.
1773 </DL>
1782 <DD>
1784 <DD>
1788 syntax, not in PO file syntax.
1791 <DD>
1793 Assume the input files are NeXTstep/GNUstep localized resource files in
1796 </DL>
1805 <DD>
1807 <DD>
1809 Specify whether or when to use colors and other text attributes.
1810 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
1813 <DD>
1816 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
1819 <DD>
1821 Always write an output file even if it contains no message.
1824 <DD>
1826 <DD>
1829 Write the .po file using indented style.
1832 <DD>
1837 <DD>
1839 <DD>
1845 <DD>
1847 Write out a strict Uniforum conforming PO file. Note that this
1848 Uniforum format should be avoided because it doesn't support the
1849 GNU extensions.
1852 <DD>
1854 <DD>
1858 that this file format doesn't support plural forms and silently drops
1859 obsolete messages.
1862 <DD>
1865 Note that this file format doesn't support plural forms.
1868 <DD>
1870 <DD>
1873 Set the output page width. Long strings in the output files will be
1874 split across multiple lines in order to ensure that each line's width
1878 <DD>
1880 Do not break long message lines. Message lines whose width exceeds the
1881 output page width will not be split into several lines. Only file reference
1882 lines which are wider than the output page width will be split.
1885 <DD>
1887 <DD>
1890 Generate sorted output. Note that using this option makes it much harder
1891 for the translator to understand each message's context.
1894 <DD>
1896 <DD>
1899 Sort output by file location.
1902 <DD>
1906 </DL>
1915 <DD>
1917 <DD>
1920 Display this help and exit.
1923 <DD>
1925 <DD>
1928 Output version information and exit.
1930 </DL>
1934 <H2><A NAME="SEC126" HREF="gettext_toc.html#TOC126">9.7 Invoking the <CODE>msgcmp</CODE> Program</A></H2>
1936 <P>
1940 <PRE>
1942 </PRE>
1944 <P>
1950 This is useful for checking that you have translated each and every message
1951 in your program. Where an exact match cannot be found, fuzzy matching is
1952 used to produce better diagnostics.
1954 </P>
1962 <DD>
1963 Translations.
1966 <DD>
1967 References to the sources.
1970 <DD>
1972 <DD>
1976 searched relative to this list of directories.
1978 </DL>
1987 <DD>
1989 <DD>
1995 <DD>
1997 <DD>
2000 Do not use fuzzy matching when an exact match is not found. This may speed
2001 up the operation considerably.
2004 <DD>
2007 Note that using this option is usually wrong, because fuzzy messages are
2008 exactly those which have not been validated by a human translator.
2011 <DD>
2014 messages. Note that using this option is usually wrong.
2016 </DL>
2025 <DD>
2027 <DD>
2031 syntax, not in PO file syntax.
2034 <DD>
2036 Assume the input files are NeXTstep/GNUstep localized resource files in
2039 </DL>
2048 <DD>
2050 <DD>
2053 Display this help and exit.
2056 <DD>
2058 <DD>
2061 Output version information and exit.
2063 </DL>
2067 <H2><A NAME="SEC131" HREF="gettext_toc.html#TOC131">9.8 Invoking the <CODE>msgattrib</CODE> Program</A></H2>
2069 <P>
2073 <PRE>
2075 </PRE>
2077 <P>
2081 according to their attributes, and manipulates the attributes.
2083 </P>
2091 <DD>
2092 Input PO file.
2095 <DD>
2097 <DD>
2102 file will be written relative to the current directory, though.
2104 </DL>
2106 <P>
2107 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
2109 </P>
2117 <DD>
2119 <DD>
2122 Write output to specified file.
2124 </DL>
2126 <P>
2127 The results are written to standard output if no output file is specified
2130 </P>
2138 <DD>
2140 Keep translated messages, remove untranslated messages.
2143 <DD>
2145 Keep untranslated messages, remove translated messages.
2148 <DD>
2150 Remove
2151 ‘fuzzy’
2152 marked messages.
2155 <DD>
2157 Keep
2158 ‘fuzzy’
2159 marked messages, remove all other messages.
2162 <DD>
2164 Remove obsolete #~ messages.
2167 <DD>
2169 Keep obsolete #~ messages, remove all other messages.
2171 </DL>
2177 <P>
2179 Attributes are modified after the message selection/removal has been
2180 performed. If the <SAMP>‘--only-file’</SAMP> or <SAMP>‘--ignore-file’</SAMP> option is
2181 specified, the attribute modification is applied only to those messages
2185 </P>
2189 <DD>
2191 Set all messages
2192 ‘fuzzy’.
2195 <DD>
2197 Set all messages
2198 non-‘fuzzy’.
2201 <DD>
2203 Set all messages obsolete.
2206 <DD>
2208 Set all messages non-obsolete.
2211 <DD>
2216 <DD>
2222 <DD>
2228 <DD>
2231 messages and removes their
2232 ‘fuzzy’
2233 mark.
2236 <DD>
2239 obsolete messages and makes them non-obsolete.
2241 </DL>
2250 <DD>
2252 <DD>
2256 syntax, not in PO file syntax.
2259 <DD>
2261 Assume the input file is a NeXTstep/GNUstep localized resource file in
2264 </DL>
2273 <DD>
2275 <DD>
2277 Specify whether or when to use colors and other text attributes.
2278 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
2281 <DD>
2284 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
2287 <DD>
2289 Always write an output file even if it contains no message.
2292 <DD>
2294 <DD>
2297 Write the .po file using indented style.
2300 <DD>
2305 <DD>
2307 <DD>
2313 <DD>
2315 Write out a strict Uniforum conforming PO file. Note that this
2316 Uniforum format should be avoided because it doesn't support the
2317 GNU extensions.
2320 <DD>
2322 <DD>
2326 that this file format doesn't support plural forms and silently drops
2327 obsolete messages.
2330 <DD>
2333 Note that this file format doesn't support plural forms.
2336 <DD>
2338 <DD>
2341 Set the output page width. Long strings in the output files will be
2342 split across multiple lines in order to ensure that each line's width
2346 <DD>
2348 Do not break long message lines. Message lines whose width exceeds the
2349 output page width will not be split into several lines. Only file reference
2350 lines which are wider than the output page width will be split.
2353 <DD>
2355 <DD>
2358 Generate sorted output. Note that using this option makes it much harder
2359 for the translator to understand each message's context.
2362 <DD>
2364 <DD>
2367 Sort output by file location.
2369 </DL>
2378 <DD>
2380 <DD>
2383 Display this help and exit.
2386 <DD>
2388 <DD>
2391 Output version information and exit.
2393 </DL>
2397 <H2><A NAME="SEC139" HREF="gettext_toc.html#TOC139">9.9 Invoking the <CODE>msgen</CODE> Program</A></H2>
2399 <P>
2403 <PRE>
2405 </PRE>
2407 <P>
2410 input file is the last created English PO file, or a PO Template file
2411 (generally created by xgettext). Untranslated entries are assigned a
2412 translation that is identical to the msgid.
2414 </P>
2415 <P>
2420 </P>
2428 <DD>
2429 Input PO or POT file.
2432 <DD>
2434 <DD>
2439 file will be written relative to the current directory, though.
2441 </DL>
2443 <P>
2446 </P>
2454 <DD>
2456 <DD>
2459 Write output to specified file.
2461 </DL>
2463 <P>
2464 The results are written to standard output if no output file is specified
2467 </P>
2475 <DD>
2477 <DD>
2481 syntax, not in PO file syntax.
2484 <DD>
2486 Assume the input file is a NeXTstep/GNUstep localized resource file in
2489 </DL>
2498 <DD>
2501 section <A HREF="gettext_6.html#SEC44">6.2 Filling in the Header Entry</A> for the meaning of this field. Note: The
2502 <SAMP>‘Language-Team’</SAMP> and <SAMP>‘Plural-Forms’</SAMP> fields are not set by this
2503 option.
2506 <DD>
2508 <DD>
2510 Specify whether or when to use colors and other text attributes.
2511 See section <A HREF="gettext_9.html#SEC150">9.11.1 The <CODE>--color</CODE> option</A> for details.
2514 <DD>
2517 See section <A HREF="gettext_9.html#SEC152">9.11.3 The <CODE>--style</CODE> option</A> for details.
2520 <DD>
2522 Always write an output file even if it contains no message.
2525 <DD>
2527 <DD>
2530 Write the .po file using indented style.
2533 <DD>
2538 <DD>
2543 <DD>
2545 Write out a strict Uniforum conforming PO file. Note that this
2546 Uniforum format should be avoided because it doesn't support the
2547 GNU extensions.
2550 <DD>
2552 <DD>
2556 that this file format doesn't support plural forms and silently drops
2557 obsolete messages.
2560 <DD>
2563 Note that this file format doesn't support plural forms.
2566 <DD>
2568 <DD>
2571 Set the output page width. Long strings in the output files will be
2572 split across multiple lines in order to ensure that each line's width
2576 <DD>
2578 Do not break long message lines. Message lines whose width exceeds the
2579 output page width will not be split into several lines. Only file reference
2580 lines which are wider than the output page width will be split.
2583 <DD>
2585 <DD>
2588 Generate sorted output. Note that using this option makes it much harder
2589 for the translator to understand each message's context.
2592 <DD>
2594 <DD>
2597 Sort output by file location.
2599 </DL>
2608 <DD>
2610 <DD>
2613 Display this help and exit.
2616 <DD>
2618 <DD>
2621 Output version information and exit.
2623 </DL>
2627 <H2><A NAME="SEC145" HREF="gettext_toc.html#TOC145">9.10 Invoking the <CODE>msgexec</CODE> Program</A></H2>
2629 <P>
2633 <PRE>
2635 </PRE>
2637 <P>
2640 translation catalog.
2642 input. It is invoked once for each translation. Its output becomes
2644 across all invocations.
2646 </P>
2647 <P>
2649 A special builtin command called <SAMP>‘0’</SAMP> outputs the translation, followed
2653 </P>
2654 <P>
2661 of the message. If the message has a context, the environment variable
2663 unbound.
2665 </P>
2666 <P>
2669 with input encoded in the translation catalog's encoding. If the
2672 program, before invoking <SAMP>‘msgexec’</SAMP>. If the <VAR>command</VAR> wants input
2673 in the locale's encoding, but you want to avoid the locale's encoding, then
2674 you can first convert the translation catalog to UTF-8 using the
2675 <SAMP>‘msgconv’</SAMP> program and then make <SAMP>‘msgexec’</SAMP> work in an UTF-8
2678 </P>
2686 <DD>
2688 <DD>
2691 Input PO file.
2694 <DD>
2696 <DD>
2701 file will be written relative to the current directory, though.
2703 </DL>
2705 <P>
2706 If no <VAR>inputfile</VAR> is given or if it is <SAMP>‘-’</SAMP>, standard input is read.
2708 </P>
2716 <DD>
2718 <DD>
2722 syntax, not in PO file syntax.
2725 <DD>
2727 Assume the input file is a NeXTstep/GNUstep localized resource file in
2730 </DL>
2739 <DD>
2741 <DD>
2744 Display this help and exit.
2747 <DD>
2749 <DD>
2752 Output version information and exit.
2754 </DL>
2758 <H2><A NAME="SEC149" HREF="gettext_toc.html#TOC149">9.11 Highlighting parts of PO files</A></H2>
2760 <P>
2761 Translators are usually only interested in seeing the untranslated and
2762 fuzzy messages of a PO file. Also, when a message is set fuzzy because
2763 the msgid changed, they want to see the differences between the previous
2764 msgid and the current one (especially if the msgid is long and only few
2765 words in it have changed). Finally, it's always welcome to highlight the
2766 different sections of a message in a PO file (comments, msgid, msgstr, etc.).
2768 </P>
2769 <P>
2773 </P>
2777 <H3><A NAME="SEC150" HREF="gettext_toc.html#TOC150">9.11.1 The <CODE>--color</CODE> option</A></H3>
2779 <P>
2783 the following:
2785 </P>
2789 <DD>
2791 <DD>
2792 The output will be colorized.
2795 <DD>
2797 <DD>
2798 The output will not be colorized.
2801 <DD>
2803 <DD>
2804 The output will be colorized if the output device is a tty, i.e. when the
2805 output goes directly to a text screen or terminal emulator window.
2808 <DD>
2809 The output will be colorized and be in HTML format.
2810 </DL>
2812 <P>
2813 <SAMP>‘--color’</SAMP> is equivalent to <SAMP>‘--color=yes’</SAMP>. The default is
2816 </P>
2817 <P>
2819 when called by itself in a command window. Whereas in a pipe, such as
2821 get colorized output in this situation nevertheless, use the command
2824 </P>
2825 <P>
2827 a browser. This can be useful, for example, for Indic languages,
2828 because the renderic of Indic scripts in browser is usually better than
2829 in terminal emulators.
2831 </P>
2832 <P>
2834 a valid PO file in itself. It contains additional terminal-specific escape
2835 sequences or HTML tags. A PO file reader will give a syntax error when
2837 you therefore normally don't need to save output produced with the
2840 </P>
2843 <H3><A NAME="SEC151" HREF="gettext_toc.html#TOC151">9.11.2 The environment variable <CODE>TERM</CODE></A></H3>
2845 <P>
2848 window's capabilities. You can get a detailed list of these cababilities
2849 by using the <SAMP>‘infocmp’</SAMP> command, using <SAMP>‘man 5 terminfo’</SAMP> as a
2850 reference.
2852 </P>
2853 <P>
2859 a different value in these cases:
2861 </P>
2865 <DD>
2872 <DD>
2877 <DD>
2880 </DL>
2882 <P>
2885 reasonable color map.
2887 </P>
2890 <H3><A NAME="SEC152" HREF="gettext_toc.html#TOC152">9.11.3 The <CODE>--style</CODE> option</A></H3>
2892 <P>
2894 The <SAMP>‘--style=<VAR>style_file</VAR>’</SAMP> option specifies the style file to use
2896 effective.
2898 </P>
2899 <P>
2903 preferred style for PO files.
2905 </P>
2906 <P>
2910 </P>
2911 <P>
2912 A few style files are predefined:
2916 <DD>
2917 This style imitates the look used by vim 7.
2920 <DD>
2924 <DD>
2926 <DD>
2928 <DD>
2929 This style imitates the look used by GNU Emacs 22 in a terminal of type
2930 <SAMP>‘xterm’</SAMP> (8 colors) or <SAMP>‘xterm-16color’</SAMP> (16 colors) or
2932 </DL>
2934 <P>
2935 You can use these styles without specifying a directory. They are actually
2936 located in <TT>‘$prefix/share/gettext/styles/’</TT>, where <CODE>$prefix</CODE> is the
2937 installation location.
2939 </P>
2940 <P>
2941 You can also design your own styles. This is described in the next section.
2943 </P>
2949 <P>
2950 The same style file can be used for styling of a PO file, for terminal
2951 output and for HTML output. It is written in CSS (Cascading Style Sheet)
2952 syntax. See <A HREF="http://www.w3.org/TR/css2/cover.html">http://www.w3.org/TR/css2/cover.html</A> for a formal
2953 definition of CSS. Many HTML authoring tutorials also contain explanations
2954 of CSS.
2956 </P>
2957 <P>
2958 In the case of HTML output, the style file is embedded in the HTML output.
2959 In the case of text output, the style file is interpreted by the
2963 </P>
2965 <UL>
2966 <LI>
2968 relative to the resulting HTML file, in the case of HTML output,
2970 <LI>
2975 </UL>
2977 <P>
2978 CSS rules are built up from selectors and declarations. The declarations
2979 specify graphical properties; the selectors specify specify when they apply.
2981 </P>
2982 <P>
2983 In PO files, the following simple selectors (based on "CSS classes", see
2984 the CSS2 spec, section 5.8.3) are supported.
2986 </P>
2988 <UL>
2989 <LI>
2991 Selectors that apply to entire messages:
2996 <DD>
2997 This matches the header entry of a PO file.
3000 <DD>
3001 This matches a translated message.
3004 <DD>
3005 This matches an untranslated message (i.e. a message with empty translation).
3008 <DD>
3009 This matches a fuzzy message (i.e. a message which has a translation that
3010 needs review by the translator).
3013 <DD>
3014 This matches an obsolete message (i.e. a message that was translated but is
3015 not needed by the current POT file any more).
3016 </DL>
3018 <LI>
3020 Selectors that apply to parts of a message in PO syntax. Recall the general
3021 structure of a message in PO syntax:
3024 <PRE>
3033 </PRE>
3038 <DD>
3039 This matches all comments (translator comments, extracted comments,
3040 source file reference comments, flag comments, previous message comments,
3041 as well as the entire obsolete messages).
3044 <DD>
3045 This matches the translator comments.
3048 <DD>
3049 This matches the extracted comments, i.e. the comments placed by the
3050 programmer at the attention of the translator.
3053 <DD>
3054 This matches the source file reference comments (entire lines).
3057 <DD>
3058 This matches the individual source file references inside the source file
3059 reference comment lines.
3062 <DD>
3063 This matches the flag comment lines (entire lines).
3066 <DD>
3067 This matches the individual flags inside flag comment lines.
3070 <DD>
3071 This matches the `fuzzy' flag inside flag comment lines.
3074 <DD>
3075 This matches the comments containing the previous untranslated string (entire
3076 lines).
3079 <DD>
3080 This matches the previous untranslated string including the string delimiters,
3084 <DD>
3085 This matches the untranslated string including the string delimiters,
3089 <DD>
3090 This matches the translated string including the string delimiters,
3094 <DD>
3098 <DD>
3099 This matches strings, including the string delimiters (double quotes).
3100 </DL>
3102 <LI>
3104 Selectors that apply to parts of strings:
3109 <DD>
3110 This matches the entire contents of a string (excluding the string delimiters,
3111 i.e. the double quotes).
3114 <DD>
3115 This matches an escape sequence (starting with a backslash).
3118 <DD>
3119 This matches a format string directive (starting with a <SAMP>‘%’</SAMP> sign in the
3121 <CODE>java-format</CODE> and <CODE>csharp-format</CODE>, with a <SAMP>‘~’</SAMP> in the case of
3122 <CODE>lisp-format</CODE> and <CODE>scheme-format</CODE>, or with <SAMP>‘$’</SAMP> in the case of
3126 <DD>
3127 This matches an invalid format string directive.
3130 <DD>
3131 In an untranslated string, this matches a part of the string that was not
3132 present in the previous untranslated string. (Not yet implemented in this
3133 release.)
3136 <DD>
3137 In an untranslated string or in a previous untranslated string, this matches
3138 a part of the string that is changed or replaced. (Not yet implemented in
3139 this release.)
3142 <DD>
3143 In a previous untranslated string, this matches a part of the string that
3144 is not present in the current untranslated string. (Not yet implemented in
3145 this release.)
3146 </DL>
3147 </UL>
3149 <P>
3150 These selectors can be combined to hierarchical selectors. For example,
3152 </P>
3154 <PRE>
3155 .msgstr .invalid-format-directive { color: red; }
3156 </PRE>
3158 <P>
3159 will highlight the invalid format directives in the translated strings.
3161 </P>
3162 <P>
3163 In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements
3164 (CSS2 spec, section 5.12) are not supported.
3166 </P>
3167 <P>
3168 The declarations in HTML mode are not limited; any graphical attribute
3169 supported by the browsers can be used.
3171 </P>
3172 <P>
3173 The declarations in text mode are limited to the following properties. Other
3174 properties will be silently ignored.
3176 </P>
3180 <DD>
3182 <DD>
3183 These properties is supported. Colors will be adjusted to match the terminal's
3184 capabilities. Note that many terminals support only 8 colors.
3187 <DD>
3188 This property is supported, but most terminals can only render two different
3193 <DD>
3195 rendered the same way.
3198 <DD>
3201 </DL>
3205 <H3><A NAME="SEC154" HREF="gettext_toc.html#TOC154">9.11.5 Customizing <CODE>less</CODE> for viewing PO files</A></H3>
3207 <P>
3209 screen or terminal emulator. It also supports text with embedded escape
3210 sequences for colors and text decorations.
3212 </P>
3213 <P>
3215 environment):
3217 </P>
3219 <PRE>
3220 msgcat --to-code=UTF-8 --color xyz.po | less -R
3221 </PRE>
3223 <P>
3224 You can simplify this to this simple command:
3226 </P>
3228 <PRE>
3229 less xyz.po
3230 </PRE>
3232 <P>
3233 after these three preparations:
3235 </P>
3237 <OL>
3238 <LI>
3240 Add the options <SAMP>‘-R’</SAMP> and <SAMP>‘-f’</SAMP> to the <CODE>LESS</CODE> environment
3241 variable. In sh shells:
3243 <PRE>
3245 $ export LESS
3246 </PRE>
3248 <LI>
3255 <LI>
3259 a temporary file. Like this:
3262 <PRE>
3263 case "$1" in
3264 *.po)
3265 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"`
3267 echo "$tmpfile"
3268 exit 0
3269 ;;
3270 esac
3271 </PRE>
3273 </OL>
3277 <H2><A NAME="SEC155" HREF="gettext_toc.html#TOC155">9.12 Writing your own programs that process PO files</A></H2>
3279 <P>
3280 For the tasks for which a combination of <SAMP>‘msgattrib’</SAMP>, <SAMP>‘msgcat’</SAMP> etc.
3281 is not sufficient, a set of C functions is provided in a library, to make it
3282 possible to process PO files in your own programs. When you use this library,
3283 you don't need to write routines to parse the PO file; instead, you retrieve
3284 a pointer in memory to each of messages contained in the PO file. Functions
3285 for writing PO files are not provided at this time.
3287 </P>
3288 <P>
3289 The functions are declared in the header file <SAMP>‘<gettext-po.h>’</SAMP>, and are
3292 </P>
3293 <P>
3294 <DL>
3297 This is a pointer type that refers to the contents of a PO file, after it has
3298 been read into memory.
3299 </DL>
3301 </P>
3302 <P>
3303 <DL>
3306 This is a pointer type that refers to an iterator that produces a sequence of
3307 messages.
3308 </DL>
3310 </P>
3311 <P>
3312 <DL>
3315 This is a pointer type that refers to a message of a PO file, including its
3316 translation.
3317 </DL>
3319 </P>
3320 <P>
3321 <DL>
3325 is given as argument. The return value is a handle to the PO file's contents,
3328 </DL>
3330 </P>
3331 <P>
3332 <DL>
3336 including all messages that are only implicitly accessible through iterators.
3337 </DL>
3339 </P>
3340 <P>
3341 <DL>
3342 <DT><U>Function:</U> const char * const * <B>po_file_domains</B> <I>(po_file_t <VAR>file</VAR>)</I>
3347 contain no <SAMP>‘domain’</SAMP> directive, the return value contains only one domain,
3349 </DL>
3351 </P>
3352 <P>
3353 <DL>
3354 <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>
3360 </DL>
3362 </P>
3363 <P>
3364 <DL>
3365 <DT><U>Function:</U> void <B>po_message_iterator_free</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I>
3369 </DL>
3371 </P>
3372 <P>
3373 <DL>
3374 <DT><U>Function:</U> po_message_t <B>po_next_message</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I>
3378 iterator has reached the end of its message list.
3379 </DL>
3381 </P>
3382 <P>
3386 </P>
3387 <P>
3388 <DL>
3389 <DT><U>Function:</U> const char * <B>po_message_msgid</B> <I>(po_message_t <VAR>message</VAR>)</I>
3393 </DL>
3395 </P>
3396 <P>
3397 <DL>
3398 <DT><U>Function:</U> const char * <B>po_message_msgid_plural</B> <I>(po_message_t <VAR>message</VAR>)</I>
3402 for a message without plural.
3403 </DL>
3405 </P>
3406 <P>
3407 <DL>
3408 <DT><U>Function:</U> const char * <B>po_message_msgstr</B> <I>(po_message_t <VAR>message</VAR>)</I>
3411 of a message. For an untranslated message, the return value is an empty
3412 string.
3413 </DL>
3415 </P>
3416 <P>
3417 <DL>
3418 <DT><U>Function:</U> const char * <B>po_message_msgstr_plural</B> <I>(po_message_t <VAR>message</VAR>, int <VAR>index</VAR>)</I>
3423 </DL>
3425 </P>
3426 <P>
3427 Here is an example code how these functions can be used.
3429 </P>
3431 <PRE>
3432 const char *filename = ...;
3433 po_file_t file = po_file_read (filename);
3435 if (file == NULL)
3436 error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename);
3437 {
3438 const char * const *domains = po_file_domains (file);
3439 const char * const *domainp;
3441 for (domainp = domains; *domainp; domainp++)
3442 {
3443 const char *domain = *domainp;
3444 po_message_iterator_t iterator = po_message_iterator (file, domain);
3446 for (;;)
3447 {
3448 po_message_t *message = po_next_message (iterator);
3450 if (message == NULL)
3451 break;
3452 {
3453 const char *msgid = po_message_msgid (message);
3454 const char *msgstr = po_message_msgstr (message);
3456 ...
3457 }
3458 }
3459 po_message_iterator_free (iterator);
3460 }
3461 }
3462 po_file_free (file);
3463 </PRE>
3465 <P><HR><P>
3466 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>.
3467 </BODY>
3468 </HTML>