<HTML> <HEAD> <!-- This HTML file has been created by texi2html 1.52a from gettext.texi on 30 November 2003 --> <TITLE>GNU gettext utilities - 7 Manipulating PO Files</TITLE> </HEAD> <BODY> Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_6.html">previous</A>, <A HREF="gettext_8.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. <P><HR><P> <H1><A NAME="SEC65" HREF="gettext_toc.html#TOC65">7 Manipulating PO Files</A></H1> <P> <A NAME="IDX479"></A> </P> <P> Sometimes it is necessary to manipulate PO files in a way that is better performed automatically than by hand. GNU <CODE>gettext</CODE> includes a complete set of tools for this purpose. </P> <P> <A NAME="IDX480"></A> When merging two packages into a single package, the resulting POT file will be the concatenation of the two packages' POT files. Thus the maintainer must concatenate the two existing package translations into a single translation catalog, for each language. This is best performed using <SAMP>`msgcat´</SAMP>. It is then the translators' duty to deal with any possible conflicts that arose during the merge. </P> <P> <A NAME="IDX481"></A> When a translator takes over the translation job from another translator, but she uses a different character encoding in her locale, she will convert the catalog to her character encoding. This is best done through the <SAMP>`msgconv´</SAMP> program. </P> <P> When a maintainer takes a source file with tagged messages from another package, he should also take the existing translations for this source file (and not let the translators do the same job twice). One way to do this is through <SAMP>`msggrep´</SAMP>, another is to create a POT file for that source file and use <SAMP>`msgmerge´</SAMP>. </P> <P> <A NAME="IDX482"></A> <A NAME="IDX483"></A> When a translator wants to adjust some translation catalog for a special dialect or orthography -- for example, German as written in Switzerland versus German as written in Germany -- she needs to apply some text processing to every message in the catalog. The tool for doing this is <SAMP>`msgfilter´</SAMP>. </P> <P> Another use of <CODE>msgfilter</CODE> is to produce approximately the POT file for which a given PO file was made. This can be done through a filter command like <SAMP>`msgfilter sed -e d | sed -e '/^# /d'´</SAMP>. Note that the original POT file may have had different comments and different plural message counts, that's why it's better to use the original POT file if available. </P> <P> <A NAME="IDX484"></A> When a translator wants to check her translations, for example according to orthography rules or using a non-interactive spell checker, she can do so using the <SAMP>`msgexec´</SAMP> program. </P> <P> <A NAME="IDX485"></A> When third party tools create PO or POT files, sometimes duplicates cannot be avoided. But the GNU <CODE>gettext</CODE> tools give an error when they encounter duplicate msgids in the same file and in the same domain. To merge duplicates, the <SAMP>`msguniq´</SAMP> program can be used. </P> <P> <SAMP>`msgcomm´</SAMP> is a more general tool for keeping or throwing away duplicates, occurring in different files. </P> <P> <SAMP>`msgcmp´</SAMP> can be used to check whether a translation catalog is completely translated. </P> <P> <A NAME="IDX486"></A> <SAMP>`msgattrib´</SAMP> can be used to select and extract only the fuzzy or untranslated messages of a translation catalog. </P> <P> <SAMP>`msgen´</SAMP> is useful as a first step for preparing English translation catalogs. It copies each message's msgid to its msgstr. </P> <P> Finally, for those applications where all these various programs are not sufficient, a library <SAMP>`libgettextpo´</SAMP> is provided that can be used to write other specialized programs that process PO files. </P> <H2><A NAME="SEC66" HREF="gettext_toc.html#TOC66">7.1 Invoking the <CODE>msgcat</CODE> Program</A></H2> <P> <A NAME="IDX487"></A> <A NAME="IDX488"></A> <PRE> msgcat [<VAR>option</VAR>] [<VAR>inputfile</VAR>]... </PRE> <P> <A NAME="IDX489"></A> <A NAME="IDX490"></A> The <CODE>msgcat</CODE> program concatenates and merges the specified PO files. It finds messages which are common to two or more of the specified PO files. By using the <CODE>--more-than</CODE> option, greater commonality may be requested before messages are printed. Conversely, the <CODE>--less-than</CODE> option may be used to specify less commonality before messages are printed (i.e. <SAMP>`--less-than=2´</SAMP> will only print the unique messages). Translations, comments and extract comments will be cumulated, except that if <CODE>--use-first</CODE> is specified, they will be taken from the first PO file to define them. File positions from all PO files will be cumulated. </P> <H3><A NAME="SEC67" HREF="gettext_toc.html#TOC67">7.1.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>inputfile</VAR> ...´</SAMP> <DD> Input files. <DT><SAMP>`-f <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--files-from=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX491"></A> <A NAME="IDX492"></A> Read the names of the input files from <VAR>file</VAR> instead of getting them from the command line. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX493"></A> <A NAME="IDX494"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If <VAR>inputfile</VAR> is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC68" HREF="gettext_toc.html#TOC68">7.1.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX495"></A> <A NAME="IDX496"></A> Write output to specified file. </DL> <P> <A NAME="IDX497"></A> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC69" HREF="gettext_toc.html#TOC69">7.1.3 Message selection</A></H3> <DL COMPACT> <DT><SAMP>`-< <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--less-than=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX498"></A> <A NAME="IDX499"></A> Print messages with less than <VAR>number</VAR> definitions, defaults to infinite if not set. <DT><SAMP>`-> <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--more-than=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX500"></A> <A NAME="IDX501"></A> Print messages with more than <VAR>number</VAR> definitions, defaults to 0 if not set. <DT><SAMP>`-u´</SAMP> <DD> <DT><SAMP>`--unique´</SAMP> <DD> <A NAME="IDX502"></A> <A NAME="IDX503"></A> Shorthand for <SAMP>`--less-than=2´</SAMP>. Requests that only unique messages be printed. </DL> <H3><A NAME="SEC70" HREF="gettext_toc.html#TOC70">7.1.4 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX504"></A> <A NAME="IDX505"></A> Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX506"></A> Assume the input files are NeXTstep/GNUstep localized resource files in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC71" HREF="gettext_toc.html#TOC71">7.1.5 Output details</A></H3> <DL COMPACT> <DT><SAMP>`-t´</SAMP> <DD> <DT><SAMP>`--to-code=<VAR>name</VAR>´</SAMP> <DD> <A NAME="IDX507"></A> <A NAME="IDX508"></A> Specify encoding for output. <DT><SAMP>`--use-first´</SAMP> <DD> <A NAME="IDX509"></A> Use first available translation for each message. Don't merge several translations into one. <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX510"></A> Always write an output file even if it contains no message. <DT><SAMP>`-i´</SAMP> <DD> <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX511"></A> <A NAME="IDX512"></A> Write the .po file using indented style. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX513"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`-n´</SAMP> <DD> <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX514"></A> <A NAME="IDX515"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX516"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX517"></A> <A NAME="IDX518"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX519"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX520"></A> <A NAME="IDX521"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX522"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`-s´</SAMP> <DD> <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX523"></A> <A NAME="IDX524"></A> <A NAME="IDX525"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX526"></A> <A NAME="IDX527"></A> Sort output by file location. </DL> <H3><A NAME="SEC72" HREF="gettext_toc.html#TOC72">7.1.6 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX528"></A> <A NAME="IDX529"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX530"></A> <A NAME="IDX531"></A> Output version information and exit. </DL> <H2><A NAME="SEC73" HREF="gettext_toc.html#TOC73">7.2 Invoking the <CODE>msgconv</CODE> Program</A></H2> <P> <A NAME="IDX532"></A> <A NAME="IDX533"></A> <PRE> msgconv [<VAR>option</VAR>] [<VAR>inputfile</VAR>] </PRE> <P> <A NAME="IDX534"></A> The <CODE>msgconv</CODE> program converts a translation catalog to a different character encoding. </P> <H3><A NAME="SEC74" HREF="gettext_toc.html#TOC74">7.2.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>inputfile</VAR>´</SAMP> <DD> Input PO file. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX535"></A> <A NAME="IDX536"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC75" HREF="gettext_toc.html#TOC75">7.2.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX537"></A> <A NAME="IDX538"></A> Write output to specified file. </DL> <P> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC76" HREF="gettext_toc.html#TOC76">7.2.3 Conversion target</A></H3> <DL COMPACT> <DT><SAMP>`-t´</SAMP> <DD> <DT><SAMP>`--to-code=<VAR>name</VAR>´</SAMP> <DD> <A NAME="IDX539"></A> <A NAME="IDX540"></A> Specify encoding for output. </DL> <P> The default encoding is the current locale's encoding. </P> <H3><A NAME="SEC77" HREF="gettext_toc.html#TOC77">7.2.4 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX541"></A> <A NAME="IDX542"></A> Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX543"></A> Assume the input file is a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC78" HREF="gettext_toc.html#TOC78">7.2.5 Output details</A></H3> <DL COMPACT> <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX544"></A> Always write an output file even if it contains no message. <DT><SAMP>`-i´</SAMP> <DD> <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX545"></A> <A NAME="IDX546"></A> Write the .po file using indented style. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX547"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX548"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX549"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX550"></A> <A NAME="IDX551"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX552"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX553"></A> <A NAME="IDX554"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX555"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`-s´</SAMP> <DD> <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX556"></A> <A NAME="IDX557"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX558"></A> <A NAME="IDX559"></A> Sort output by file location. </DL> <H3><A NAME="SEC79" HREF="gettext_toc.html#TOC79">7.2.6 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX560"></A> <A NAME="IDX561"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX562"></A> <A NAME="IDX563"></A> Output version information and exit. </DL> <H2><A NAME="SEC80" HREF="gettext_toc.html#TOC80">7.3 Invoking the <CODE>msggrep</CODE> Program</A></H2> <P> <A NAME="IDX564"></A> <A NAME="IDX565"></A> <PRE> msggrep [<VAR>option</VAR>] [<VAR>inputfile</VAR>] </PRE> <P> <A NAME="IDX566"></A> The <CODE>msggrep</CODE> program extracts all messages of a translation catalog that match a given pattern or belong to some given source files. </P> <H3><A NAME="SEC81" HREF="gettext_toc.html#TOC81">7.3.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>inputfile</VAR>´</SAMP> <DD> Input PO file. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX567"></A> <A NAME="IDX568"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC82" HREF="gettext_toc.html#TOC82">7.3.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX569"></A> <A NAME="IDX570"></A> Write output to specified file. </DL> <P> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC83" HREF="gettext_toc.html#TOC83">7.3.3 Message selection</A></H3> <PRE> [-N <VAR>sourcefile</VAR>]... [-M <VAR>domainname</VAR>]... [-K <VAR>msgid-pattern</VAR>] [-T <VAR>msgstr-pattern</VAR>] [-C <VAR>comment-pattern</VAR>] </PRE> <P> A message is selected if <UL> <LI>it comes from one of the specified source files, <LI>or if it comes from one of the specified domains, <LI>or if <SAMP>`-K´</SAMP> is given and its key (msgid or msgid_plural) matches <VAR>msgid-pattern</VAR>, <LI>or if <SAMP>`-T´</SAMP> is given and its translation (msgstr) matches <VAR>msgstr-pattern</VAR>, <LI>or if <SAMP>`-C´</SAMP> is given and the translator's comment matches <VAR>comment-pattern</VAR>. </UL> <P> When more than one selection criterion is specified, the set of selected messages is the union of the selected messages of each criterion. </P> <P> <VAR>msgid-pattern</VAR> or <VAR>msgstr-pattern</VAR> syntax: <PRE> [-E | -F] [-e <VAR>pattern</VAR> | -f <VAR>file</VAR>]... </PRE> <P> <VAR>pattern</VAR>s are basic regular expressions by default, or extended regular expressions if -E is given, or fixed strings if -F is given. </P> <DL COMPACT> <DT><SAMP>`-N <VAR>sourcefile</VAR>´</SAMP> <DD> <DT><SAMP>`--location=<VAR>sourcefile</VAR>´</SAMP> <DD> <A NAME="IDX571"></A> <A NAME="IDX572"></A> Select messages extracted from <VAR>sourcefile</VAR>. <VAR>sourcefile</VAR> can be either a literal file name or a wildcard pattern. <DT><SAMP>`-M <VAR>domainname</VAR>´</SAMP> <DD> <DT><SAMP>`--domain=<VAR>domainname</VAR>´</SAMP> <DD> <A NAME="IDX573"></A> <A NAME="IDX574"></A> Select messages belonging to domain <VAR>domainname</VAR>. <DT><SAMP>`-K´</SAMP> <DD> <DT><SAMP>`--msgid´</SAMP> <DD> <A NAME="IDX575"></A> <A NAME="IDX576"></A> Start of patterns for the msgid. <DT><SAMP>`-T´</SAMP> <DD> <DT><SAMP>`--msgstr´</SAMP> <DD> <A NAME="IDX577"></A> <A NAME="IDX578"></A> Start of patterns for the msgstr. <DT><SAMP>`-C´</SAMP> <DD> <DT><SAMP>`--comment´</SAMP> <DD> <A NAME="IDX579"></A> <A NAME="IDX580"></A> Start of patterns for the translator's comment. <DT><SAMP>`-E´</SAMP> <DD> <DT><SAMP>`--extended-regexp´</SAMP> <DD> <A NAME="IDX581"></A> <A NAME="IDX582"></A> Specify that <VAR>pattern</VAR> is an extended regular expression. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--fixed-strings´</SAMP> <DD> <A NAME="IDX583"></A> <A NAME="IDX584"></A> Specify that <VAR>pattern</VAR> is a set of newline-separated strings. <DT><SAMP>`-e <VAR>pattern</VAR>´</SAMP> <DD> <DT><SAMP>`--regexp=<VAR>pattern</VAR>´</SAMP> <DD> <A NAME="IDX585"></A> <A NAME="IDX586"></A> Use <VAR>pattern</VAR> as a regular expression. <DT><SAMP>`-f <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX587"></A> <A NAME="IDX588"></A> Obtain <VAR>pattern</VAR> from <VAR>file</VAR>. <DT><SAMP>`-i´</SAMP> <DD> <DT><SAMP>`--ignore-case´</SAMP> <DD> <A NAME="IDX589"></A> <A NAME="IDX590"></A> Ignore case distinctions. </DL> <H3><A NAME="SEC84" HREF="gettext_toc.html#TOC84">7.3.4 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX591"></A> <A NAME="IDX592"></A> Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX593"></A> Assume the input file is a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC85" HREF="gettext_toc.html#TOC85">7.3.5 Output details</A></H3> <DL COMPACT> <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX594"></A> Always write an output file even if it contains no message. <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX595"></A> Write the .po file using indented style. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX596"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX597"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX598"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX599"></A> <A NAME="IDX600"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX601"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX602"></A> <A NAME="IDX603"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX604"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX605"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX606"></A> Sort output by file location. </DL> <H3><A NAME="SEC86" HREF="gettext_toc.html#TOC86">7.3.6 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX607"></A> <A NAME="IDX608"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX609"></A> <A NAME="IDX610"></A> Output version information and exit. </DL> <H2><A NAME="SEC87" HREF="gettext_toc.html#TOC87">7.4 Invoking the <CODE>msgfilter</CODE> Program</A></H2> <P> <A NAME="IDX611"></A> <A NAME="IDX612"></A> <PRE> msgfilter [<VAR>option</VAR>] <VAR>filter</VAR> [<VAR>filter-option</VAR>] </PRE> <P> <A NAME="IDX613"></A> The <CODE>msgfilter</CODE> program applies a filter to all translations of a translation catalog. </P> <H3><A NAME="SEC88" HREF="gettext_toc.html#TOC88">7.4.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`-i <VAR>inputfile</VAR>´</SAMP> <DD> <DT><SAMP>`--input=<VAR>inputfile</VAR>´</SAMP> <DD> <A NAME="IDX614"></A> <A NAME="IDX615"></A> Input PO file. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX616"></A> <A NAME="IDX617"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC89" HREF="gettext_toc.html#TOC89">7.4.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX618"></A> <A NAME="IDX619"></A> Write output to specified file. </DL> <P> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC90" HREF="gettext_toc.html#TOC90">7.4.3 The filter</A></H3> <P> The <VAR>filter</VAR> can be any program that reads a translation from standard input and writes a modified translation to standard output. A frequently used filter is <SAMP>`sed´</SAMP>. </P> <P> <A NAME="IDX620"></A> Note: It is your responsibility to ensure that the <VAR>filter</VAR> can cope with input encoded in the translation catalog's encoding. If the <VAR>filter</VAR> wants input in a particular encoding, you can in a first step convert the translation catalog to that encoding using the <SAMP>`msgconv´</SAMP> program, before invoking <SAMP>`msgfilter´</SAMP>. If the <VAR>filter</VAR> wants input in the locale's encoding, but you want to avoid the locale's encoding, then you can first convert the translation catalog to UTF-8 using the <SAMP>`msgconv´</SAMP> program and then make <SAMP>`msgfilter´</SAMP> work in an UTF-8 locale, by using the <CODE>LC_ALL</CODE> environment variable. </P> <P> <A NAME="IDX621"></A> Note: Most translations in a translation catalog don't end with a newline character. For this reason, it is important that the <VAR>filter</VAR> recognizes its last input line even if it ends without a newline, and that it doesn't add an undesired trailing newline at the end. The <SAMP>`sed´</SAMP> program on some platforms is known to ignore the last line of input if it is not terminated with a newline. You can use GNU <CODE>sed</CODE> instead; it does not have this limitation. </P> <H3><A NAME="SEC91" HREF="gettext_toc.html#TOC91">7.4.4 Useful <VAR>filter-option</VAR>s when the <VAR>filter</VAR> is <SAMP>`sed´</SAMP></A></H3> <DL COMPACT> <DT><SAMP>`-e <VAR>script</VAR>´</SAMP> <DD> <DT><SAMP>`--expression=<VAR>script</VAR>´</SAMP> <DD> <A NAME="IDX622"></A> <A NAME="IDX623"></A> Add <VAR>script</VAR> to the commands to be executed. <DT><SAMP>`-f <VAR>scriptfile</VAR>´</SAMP> <DD> <DT><SAMP>`--file=<VAR>scriptfile</VAR>´</SAMP> <DD> <A NAME="IDX624"></A> <A NAME="IDX625"></A> Add the contents of <VAR>scriptfile</VAR> to the commands to be executed. <DT><SAMP>`-n´</SAMP> <DD> <DT><SAMP>`--quiet´</SAMP> <DD> <DT><SAMP>`--silent´</SAMP> <DD> <A NAME="IDX626"></A> <A NAME="IDX627"></A> <A NAME="IDX628"></A> Suppress automatic printing of pattern space. </DL> <H3><A NAME="SEC92" HREF="gettext_toc.html#TOC92">7.4.5 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX629"></A> <A NAME="IDX630"></A> Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX631"></A> Assume the input file is a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC93" HREF="gettext_toc.html#TOC93">7.4.6 Output details</A></H3> <DL COMPACT> <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX632"></A> Always write an output file even if it contains no message. <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX633"></A> Write the .po file using indented style. <DT><SAMP>`--keep-header´</SAMP> <DD> <A NAME="IDX634"></A> Keep the header entry, i.e. the message with <SAMP>`msgid ""´</SAMP>, unmodified, instead of filtering it. By default, the header entry is subject to filtering like any other message. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX635"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX636"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX637"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX638"></A> <A NAME="IDX639"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX640"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX641"></A> <A NAME="IDX642"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX643"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`-s´</SAMP> <DD> <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX644"></A> <A NAME="IDX645"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX646"></A> <A NAME="IDX647"></A> Sort output by file location. </DL> <H3><A NAME="SEC94" HREF="gettext_toc.html#TOC94">7.4.7 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX648"></A> <A NAME="IDX649"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX650"></A> <A NAME="IDX651"></A> Output version information and exit. </DL> <H2><A NAME="SEC95" HREF="gettext_toc.html#TOC95">7.5 Invoking the <CODE>msguniq</CODE> Program</A></H2> <P> <A NAME="IDX652"></A> <A NAME="IDX653"></A> <PRE> msguniq [<VAR>option</VAR>] [<VAR>inputfile</VAR>] </PRE> <P> <A NAME="IDX654"></A> <A NAME="IDX655"></A> The <CODE>msguniq</CODE> program unifies duplicate translations in a translation catalog. It finds duplicate translations of the same message ID. Such duplicates are invalid input for other programs like <CODE>msgfmt</CODE>, <CODE>msgmerge</CODE> or <CODE>msgcat</CODE>. By default, duplicates are merged together. When using the <SAMP>`--repeated´</SAMP> option, only duplicates are output, and all other messages are discarded. Comments and extracted comments will be cumulated, except that if <SAMP>`--use-first´</SAMP> is specified, they will be taken from the first translation. File positions will be cumulated. When using the <SAMP>`--unique´</SAMP> option, duplicates are discarded. </P> <H3><A NAME="SEC96" HREF="gettext_toc.html#TOC96">7.5.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>inputfile</VAR>´</SAMP> <DD> Input PO file. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX656"></A> <A NAME="IDX657"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC97" HREF="gettext_toc.html#TOC97">7.5.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX658"></A> <A NAME="IDX659"></A> Write output to specified file. </DL> <P> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC98" HREF="gettext_toc.html#TOC98">7.5.3 Message selection</A></H3> <DL COMPACT> <DT><SAMP>`-d´</SAMP> <DD> <DT><SAMP>`--repeated´</SAMP> <DD> <A NAME="IDX660"></A> <A NAME="IDX661"></A> Print only duplicates. <DT><SAMP>`-u´</SAMP> <DD> <DT><SAMP>`--unique´</SAMP> <DD> <A NAME="IDX662"></A> <A NAME="IDX663"></A> Print only unique messages, discard duplicates. </DL> <H3><A NAME="SEC99" HREF="gettext_toc.html#TOC99">7.5.4 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX664"></A> <A NAME="IDX665"></A> Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX666"></A> Assume the input file is a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC100" HREF="gettext_toc.html#TOC100">7.5.5 Output details</A></H3> <DL COMPACT> <DT><SAMP>`-t´</SAMP> <DD> <DT><SAMP>`--to-code=<VAR>name</VAR>´</SAMP> <DD> <A NAME="IDX667"></A> <A NAME="IDX668"></A> Specify encoding for output. <DT><SAMP>`--use-first´</SAMP> <DD> <A NAME="IDX669"></A> Use first available translation for each message. Don't merge several translations into one. <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX670"></A> Always write an output file even if it contains no message. <DT><SAMP>`-i´</SAMP> <DD> <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX671"></A> <A NAME="IDX672"></A> Write the .po file using indented style. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX673"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`-n´</SAMP> <DD> <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX674"></A> <A NAME="IDX675"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX676"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX677"></A> <A NAME="IDX678"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX679"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX680"></A> <A NAME="IDX681"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX682"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`-s´</SAMP> <DD> <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX683"></A> <A NAME="IDX684"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX685"></A> <A NAME="IDX686"></A> Sort output by file location. </DL> <H3><A NAME="SEC101" HREF="gettext_toc.html#TOC101">7.5.6 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX687"></A> <A NAME="IDX688"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX689"></A> <A NAME="IDX690"></A> Output version information and exit. </DL> <H2><A NAME="SEC102" HREF="gettext_toc.html#TOC102">7.6 Invoking the <CODE>msgcomm</CODE> Program</A></H2> <P> <A NAME="IDX691"></A> <A NAME="IDX692"></A> <PRE> msgcomm [<VAR>option</VAR>] [<VAR>inputfile</VAR>]... </PRE> <P> <A NAME="IDX693"></A> The <CODE>msgcomm</CODE> program finds messages which are common to two or more of the specified PO files. By using the <CODE>--more-than</CODE> option, greater commonality may be requested before messages are printed. Conversely, the <CODE>--less-than</CODE> option may be used to specify less commonality before messages are printed (i.e. <SAMP>`--less-than=2´</SAMP> will only print the unique messages). Translations, comments and extract comments will be preserved, but only from the first PO file to define them. File positions from all PO files will be cumulated. </P> <H3><A NAME="SEC103" HREF="gettext_toc.html#TOC103">7.6.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>inputfile</VAR> ...´</SAMP> <DD> Input files. <DT><SAMP>`-f <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--files-from=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX694"></A> <A NAME="IDX695"></A> Read the names of the input files from <VAR>file</VAR> instead of getting them from the command line. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX696"></A> <A NAME="IDX697"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If <VAR>inputfile</VAR> is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC104" HREF="gettext_toc.html#TOC104">7.6.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX698"></A> <A NAME="IDX699"></A> Write output to specified file. </DL> <P> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC105" HREF="gettext_toc.html#TOC105">7.6.3 Message selection</A></H3> <DL COMPACT> <DT><SAMP>`-< <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--less-than=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX700"></A> <A NAME="IDX701"></A> Print messages with less than <VAR>number</VAR> definitions, defaults to infinite if not set. <DT><SAMP>`-> <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--more-than=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX702"></A> <A NAME="IDX703"></A> Print messages with more than <VAR>number</VAR> definitions, defaults to 1 if not set. <DT><SAMP>`-u´</SAMP> <DD> <DT><SAMP>`--unique´</SAMP> <DD> <A NAME="IDX704"></A> <A NAME="IDX705"></A> Shorthand for <SAMP>`--less-than=2´</SAMP>. Requests that only unique messages be printed. </DL> <H3><A NAME="SEC106" HREF="gettext_toc.html#TOC106">7.6.4 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX706"></A> <A NAME="IDX707"></A> Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX708"></A> Assume the input files are NeXTstep/GNUstep localized resource files in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC107" HREF="gettext_toc.html#TOC107">7.6.5 Output details</A></H3> <DL COMPACT> <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX709"></A> Always write an output file even if it contains no message. <DT><SAMP>`-i´</SAMP> <DD> <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX710"></A> <A NAME="IDX711"></A> Write the .po file using indented style. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX712"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`-n´</SAMP> <DD> <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX713"></A> <A NAME="IDX714"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX715"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX716"></A> <A NAME="IDX717"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX718"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX719"></A> <A NAME="IDX720"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX721"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`-s´</SAMP> <DD> <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX722"></A> <A NAME="IDX723"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX724"></A> <A NAME="IDX725"></A> Sort output by file location. <DT><SAMP>`--omit-header´</SAMP> <DD> <A NAME="IDX726"></A> Don't write header with <SAMP>`msgid ""´</SAMP> entry. </DL> <H3><A NAME="SEC108" HREF="gettext_toc.html#TOC108">7.6.6 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX727"></A> <A NAME="IDX728"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX729"></A> <A NAME="IDX730"></A> Output version information and exit. </DL> <H2><A NAME="SEC109" HREF="gettext_toc.html#TOC109">7.7 Invoking the <CODE>msgcmp</CODE> Program</A></H2> <P> <A NAME="IDX731"></A> <A NAME="IDX732"></A> <PRE> msgcmp [<VAR>option</VAR>] <VAR>def</VAR>.po <VAR>ref</VAR>.pot </PRE> <P> <A NAME="IDX733"></A> The <CODE>msgcmp</CODE> program compares two Uniforum style .po files to check that both contain the same set of msgid strings. The <VAR>def</VAR>.po file is an existing PO file with the translations. The <VAR>ref</VAR>.pot file is the last created PO file, or a PO Template file (generally created by <CODE>xgettext</CODE>). This is useful for checking that you have translated each and every message in your program. Where an exact match cannot be found, fuzzy matching is used to produce better diagnostics. </P> <H3><A NAME="SEC110" HREF="gettext_toc.html#TOC110">7.7.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>def</VAR>.po´</SAMP> <DD> Translations. <DT><SAMP>`<VAR>ref</VAR>.pot´</SAMP> <DD> References to the sources. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX734"></A> <A NAME="IDX735"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. </DL> <H3><A NAME="SEC111" HREF="gettext_toc.html#TOC111">7.7.2 Operation modifiers</A></H3> <DL COMPACT> <DT><SAMP>`-m´</SAMP> <DD> <DT><SAMP>`--multi-domain´</SAMP> <DD> <A NAME="IDX736"></A> <A NAME="IDX737"></A> Apply <VAR>ref</VAR>.pot to each of the domains in <VAR>def</VAR>.po. </DL> <H3><A NAME="SEC112" HREF="gettext_toc.html#TOC112">7.7.3 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX738"></A> <A NAME="IDX739"></A> Assume the input files are Java ResourceBundles in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX740"></A> Assume the input files are NeXTstep/GNUstep localized resource files in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC113" HREF="gettext_toc.html#TOC113">7.7.4 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX741"></A> <A NAME="IDX742"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX743"></A> <A NAME="IDX744"></A> Output version information and exit. </DL> <H2><A NAME="SEC114" HREF="gettext_toc.html#TOC114">7.8 Invoking the <CODE>msgattrib</CODE> Program</A></H2> <P> <A NAME="IDX745"></A> <A NAME="IDX746"></A> <PRE> msgattrib [<VAR>option</VAR>] [<VAR>inputfile</VAR>] </PRE> <P> <A NAME="IDX747"></A> <A NAME="IDX748"></A> The <CODE>msgattrib</CODE> program filters the messages of a translation catalog according to their attributes, and manipulates the attributes. </P> <H3><A NAME="SEC115" HREF="gettext_toc.html#TOC115">7.8.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>inputfile</VAR>´</SAMP> <DD> Input PO file. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX749"></A> <A NAME="IDX750"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC116" HREF="gettext_toc.html#TOC116">7.8.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX751"></A> <A NAME="IDX752"></A> Write output to specified file. </DL> <P> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC117" HREF="gettext_toc.html#TOC117">7.8.3 Message selection</A></H3> <DL COMPACT> <DT><SAMP>`--translated´</SAMP> <DD> <A NAME="IDX753"></A> Keep translated messages, remove untranslated messages. <DT><SAMP>`--untranslated´</SAMP> <DD> <A NAME="IDX754"></A> Keep untranslated messages, remove translated messages. <DT><SAMP>`--no-fuzzy´</SAMP> <DD> <A NAME="IDX755"></A> Remove `fuzzy' marked messages. <DT><SAMP>`--only-fuzzy´</SAMP> <DD> <A NAME="IDX756"></A> Keep `fuzzy' marked messages, remove all other messsages. <DT><SAMP>`--no-obsolete´</SAMP> <DD> <A NAME="IDX757"></A> Remove obsolete #~ messages. <DT><SAMP>`--only-obsolete´</SAMP> <DD> <A NAME="IDX758"></A> Keep obsolete #~ messages, remove all other messages. </DL> <H3><A NAME="SEC118" HREF="gettext_toc.html#TOC118">7.8.4 Attribute manipulation</A></H3> <P> <A NAME="IDX759"></A> Attributes are modified after the message selection/removal has been performed. If the <SAMP>`--only-file´</SAMP> or <SAMP>`--ignore-file´</SAMP> option is specified, the attribute modification is applied only to those messages that are listed in the <VAR>only-file</VAR> and not listed in the <VAR>ignore-file</VAR>. </P> <DL COMPACT> <DT><SAMP>`--set-fuzzy´</SAMP> <DD> <A NAME="IDX760"></A> Set all messages `fuzzy'. <DT><SAMP>`--clear-fuzzy´</SAMP> <DD> <A NAME="IDX761"></A> Set all messages non-`fuzzy'. <DT><SAMP>`--set-obsolete´</SAMP> <DD> <A NAME="IDX762"></A> Set all messages obsolete. <DT><SAMP>`--clear-obsolete´</SAMP> <DD> <A NAME="IDX763"></A> Set all messages non-obsolete. <DT><SAMP>`--only-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX764"></A> Limit the attribute changes to entries that are listed in <VAR>file</VAR>. <VAR>file</VAR> should be a PO or POT file. <DT><SAMP>`--ignore-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX765"></A> Limit the attribute changes to entries that are not listed in <VAR>file</VAR>. <VAR>file</VAR> should be a PO or POT file. <DT><SAMP>`--fuzzy´</SAMP> <DD> <A NAME="IDX766"></A> Synonym for <SAMP>`--only-fuzzy --clear-fuzzy´</SAMP>: It keeps only the fuzzy messages and removes their `fuzzy' mark. <DT><SAMP>`--obsolete´</SAMP> <DD> <A NAME="IDX767"></A> Synonym for <SAMP>`--only-obsolete --clear-obsolete´</SAMP>: It keeps only the obsolete messages and makes them non-obsolete. </DL> <H3><A NAME="SEC119" HREF="gettext_toc.html#TOC119">7.8.5 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX768"></A> <A NAME="IDX769"></A> Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX770"></A> Assume the input file is a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC120" HREF="gettext_toc.html#TOC120">7.8.6 Output details</A></H3> <DL COMPACT> <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX771"></A> Always write an output file even if it contains no message. <DT><SAMP>`-i´</SAMP> <DD> <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX772"></A> <A NAME="IDX773"></A> Write the .po file using indented style. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX774"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`-n´</SAMP> <DD> <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX775"></A> <A NAME="IDX776"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX777"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX778"></A> <A NAME="IDX779"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX780"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX781"></A> <A NAME="IDX782"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX783"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`-s´</SAMP> <DD> <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX784"></A> <A NAME="IDX785"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX786"></A> <A NAME="IDX787"></A> Sort output by file location. </DL> <H3><A NAME="SEC121" HREF="gettext_toc.html#TOC121">7.8.7 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX788"></A> <A NAME="IDX789"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX790"></A> <A NAME="IDX791"></A> Output version information and exit. </DL> <H2><A NAME="SEC122" HREF="gettext_toc.html#TOC122">7.9 Invoking the <CODE>msgen</CODE> Program</A></H2> <P> <A NAME="IDX792"></A> <A NAME="IDX793"></A> <PRE> msgen [<VAR>option</VAR>] <VAR>inputfile</VAR> </PRE> <P> <A NAME="IDX794"></A> The <CODE>msgen</CODE> program creates an English translation catalog. The input file is the last created English PO file, or a PO Template file (generally created by xgettext). Untranslated entries are assigned a translation that is identical to the msgid. </P> <P> Note: <SAMP>`msginit --no-translator --locale=en´</SAMP> performs a very similar task. The main difference is that <CODE>msginit</CODE> cares specially about the header entry, whereas <CODE>msgen</CODE> doesn't. </P> <H3><A NAME="SEC123" HREF="gettext_toc.html#TOC123">7.9.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`<VAR>inputfile</VAR>´</SAMP> <DD> Input PO or POT file. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX795"></A> <A NAME="IDX796"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If <VAR>inputfile</VAR> is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC124" HREF="gettext_toc.html#TOC124">7.9.2 Output file location</A></H3> <DL COMPACT> <DT><SAMP>`-o <VAR>file</VAR>´</SAMP> <DD> <DT><SAMP>`--output-file=<VAR>file</VAR>´</SAMP> <DD> <A NAME="IDX797"></A> <A NAME="IDX798"></A> Write output to specified file. </DL> <P> The results are written to standard output if no output file is specified or if it is <SAMP>`-´</SAMP>. </P> <H3><A NAME="SEC125" HREF="gettext_toc.html#TOC125">7.9.3 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX799"></A> <A NAME="IDX800"></A> Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX801"></A> Assume the input file is a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC126" HREF="gettext_toc.html#TOC126">7.9.4 Output details</A></H3> <DL COMPACT> <DT><SAMP>`--force-po´</SAMP> <DD> <A NAME="IDX802"></A> Always write an output file even if it contains no message. <DT><SAMP>`-i´</SAMP> <DD> <DT><SAMP>`--indent´</SAMP> <DD> <A NAME="IDX803"></A> <A NAME="IDX804"></A> Write the .po file using indented style. <DT><SAMP>`--no-location´</SAMP> <DD> <A NAME="IDX805"></A> Do not write <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines. <DT><SAMP>`--add-location´</SAMP> <DD> <A NAME="IDX806"></A> Generate <SAMP>`#: <VAR>filename</VAR>:<VAR>line</VAR>´</SAMP> lines (default). <DT><SAMP>`--strict´</SAMP> <DD> <A NAME="IDX807"></A> Write out a strict Uniforum conforming PO file. Note that this Uniforum format should be avoided because it doesn't support the GNU extensions. <DT><SAMP>`-p´</SAMP> <DD> <DT><SAMP>`--properties-output´</SAMP> <DD> <A NAME="IDX808"></A> <A NAME="IDX809"></A> Write out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note that this file format doesn't support plural forms and silently drops obsolete messages. <DT><SAMP>`--stringtable-output´</SAMP> <DD> <A NAME="IDX810"></A> Write out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. Note that this file format doesn't support plural forms. <DT><SAMP>`-w <VAR>number</VAR>´</SAMP> <DD> <DT><SAMP>`--width=<VAR>number</VAR>´</SAMP> <DD> <A NAME="IDX811"></A> <A NAME="IDX812"></A> Set the output page width. Long strings in the output files will be split across multiple lines in order to ensure that each line's width (= number of screen columns) is less or equal to the given <VAR>number</VAR>. <DT><SAMP>`--no-wrap´</SAMP> <DD> <A NAME="IDX813"></A> Do not break long message lines. Message lines whose width exceeds the output page width will not be split into several lines. Only file reference lines which are wider than the output page width will be split. <DT><SAMP>`-s´</SAMP> <DD> <DT><SAMP>`--sort-output´</SAMP> <DD> <A NAME="IDX814"></A> <A NAME="IDX815"></A> Generate sorted output. Note that using this option makes it much harder for the translator to understand each message's context. <DT><SAMP>`-F´</SAMP> <DD> <DT><SAMP>`--sort-by-file´</SAMP> <DD> <A NAME="IDX816"></A> <A NAME="IDX817"></A> Sort output by file location. </DL> <H3><A NAME="SEC127" HREF="gettext_toc.html#TOC127">7.9.5 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX818"></A> <A NAME="IDX819"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX820"></A> <A NAME="IDX821"></A> Output version information and exit. </DL> <H2><A NAME="SEC128" HREF="gettext_toc.html#TOC128">7.10 Invoking the <CODE>msgexec</CODE> Program</A></H2> <P> <A NAME="IDX822"></A> <A NAME="IDX823"></A> <PRE> msgexec [<VAR>option</VAR>] <VAR>command</VAR> [<VAR>command-option</VAR>] </PRE> <P> <A NAME="IDX824"></A> The <CODE>msgexec</CODE> program applies a command to all translations of a translation catalog. The <VAR>command</VAR> can be any program that reads a translation from standard input. It is invoked once for each translation. Its output becomes msgexec's output. <CODE>msgexec</CODE>'s return code is the maximum return code across all invocations. </P> <P> <A NAME="IDX825"></A> A special builtin command called <SAMP>`0´</SAMP> outputs the translation, followed by a null byte. The output of <SAMP>`msgexec 0´</SAMP> is suitable as input for <SAMP>`xargs -0´</SAMP>. </P> <P> <A NAME="IDX826"></A> <A NAME="IDX827"></A> During each <VAR>command</VAR> invocation, the environment variable <CODE>MSGEXEC_MSGID</CODE> is bound to the message's msgid, and the environment variable <CODE>MSGEXEC_LOCATION</CODE> is bound to the location in the PO file of the message. </P> <P> <A NAME="IDX828"></A> Note: It is your responsibility to ensure that the <VAR>command</VAR> can cope with input encoded in the translation catalog's encoding. If the <VAR>command</VAR> wants input in a particular encoding, you can in a first step convert the translation catalog to that encoding using the <SAMP>`msgconv´</SAMP> program, before invoking <SAMP>`msgexec´</SAMP>. If the <VAR>command</VAR> wants input in the locale's encoding, but you want to avoid the locale's encoding, then you can first convert the translation catalog to UTF-8 using the <SAMP>`msgconv´</SAMP> program and then make <SAMP>`msgexec´</SAMP> work in an UTF-8 locale, by using the <CODE>LC_ALL</CODE> environment variable. </P> <H3><A NAME="SEC129" HREF="gettext_toc.html#TOC129">7.10.1 Input file location</A></H3> <DL COMPACT> <DT><SAMP>`-i <VAR>inputfile</VAR>´</SAMP> <DD> <DT><SAMP>`--input=<VAR>inputfile</VAR>´</SAMP> <DD> <A NAME="IDX829"></A> <A NAME="IDX830"></A> Input PO file. <DT><SAMP>`-D <VAR>directory</VAR>´</SAMP> <DD> <DT><SAMP>`--directory=<VAR>directory</VAR>´</SAMP> <DD> <A NAME="IDX831"></A> <A NAME="IDX832"></A> Add <VAR>directory</VAR> to the list of directories. Source files are searched relative to this list of directories. The resulting <TT>`.po´</TT> file will be written relative to the current directory, though. </DL> <P> If no <VAR>inputfile</VAR> is given or if it is <SAMP>`-´</SAMP>, standard input is read. </P> <H3><A NAME="SEC130" HREF="gettext_toc.html#TOC130">7.10.2 Input file syntax</A></H3> <DL COMPACT> <DT><SAMP>`-P´</SAMP> <DD> <DT><SAMP>`--properties-input´</SAMP> <DD> <A NAME="IDX833"></A> <A NAME="IDX834"></A> Assume the input file is a Java ResourceBundle in Java <CODE>.properties</CODE> syntax, not in PO file syntax. <DT><SAMP>`--stringtable-input´</SAMP> <DD> <A NAME="IDX835"></A> Assume the input file is a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax, not in PO file syntax. </DL> <H3><A NAME="SEC131" HREF="gettext_toc.html#TOC131">7.10.3 Informative output</A></H3> <DL COMPACT> <DT><SAMP>`-h´</SAMP> <DD> <DT><SAMP>`--help´</SAMP> <DD> <A NAME="IDX836"></A> <A NAME="IDX837"></A> Display this help and exit. <DT><SAMP>`-V´</SAMP> <DD> <DT><SAMP>`--version´</SAMP> <DD> <A NAME="IDX838"></A> <A NAME="IDX839"></A> Output version information and exit. </DL> <H2><A NAME="SEC132" HREF="gettext_toc.html#TOC132">7.11 Writing your own programs that process PO files</A></H2> <P> For the tasks for which a combination of <SAMP>`msgattrib´</SAMP>, <SAMP>`msgcat´</SAMP> etc. is not sufficient, a set of C functions is provided in a library, to make it possible to process PO files in your own programs. When you use this library, you don't need to write routines to parse the PO file; instead, you retreive a pointer in memory to each of messages contained in the PO file. Functions for writing PO files are not provided at this time. </P> <P> The functions are declared in the header file <SAMP>`<gettext-po.h>´</SAMP>, and are defined in a library called <SAMP>`libgettextpo´</SAMP>. </P> <P> <DL> <DT><U>Data Type:</U> <B>po_file_t</B> <DD><A NAME="IDX840"></A> This is a pointer type that refers to the contents of a PO file, after it has been read into memory. </DL> </P> <P> <DL> <DT><U>Data Type:</U> <B>po_message_iterator_t</B> <DD><A NAME="IDX841"></A> This is a pointer type that refers to an iterator that produces a sequence of messages. </DL> </P> <P> <DL> <DT><U>Data Type:</U> <B>po_message_t</B> <DD><A NAME="IDX842"></A> This is a pointer type that refers to a message of a PO file, including its translation. </DL> </P> <P> <DL> <DT><U>Function:</U> po_file_t <B>po_file_read</B> <I>(const char *<VAR>filename</VAR>)</I> <DD><A NAME="IDX843"></A> The <CODE>po_file_read</CODE> function reads a PO file into memory. The file name is given as argument. The return value is a handle to the PO file's contents, valid until <CODE>po_file_free</CODE> is called on it. In case of error, the return value is <CODE>NULL</CODE>, and <CODE>errno</CODE> is set. </DL> </P> <P> <DL> <DT><U>Function:</U> void <B>po_file_free</B> <I>(po_file_t <VAR>file</VAR>)</I> <DD><A NAME="IDX844"></A> The <CODE>po_file_free</CODE> function frees a PO file's contents from memory, including all messages that are only implicitly accessible through iterators. </DL> </P> <P> <DL> <DT><U>Function:</U> const char * const * <B>po_file_domains</B> <I>(po_file_t <VAR>file</VAR>)</I> <DD><A NAME="IDX845"></A> The <CODE>po_file_domains</CODE> function returns the domains for which the given PO file has messages. The return value is a <CODE>NULL</CODE> terminated array which is valid as long as the <VAR>file</VAR> handle is valid. For PO files which contain no <SAMP>`domain´</SAMP> directive, the return value contains only one domain, namely the default domain <CODE>"messages"</CODE>. </DL> </P> <P> <DL> <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> <DD><A NAME="IDX846"></A> The <CODE>po_message_iterator</CODE> returns an iterator that will produce the messages of <VAR>file</VAR> that belong to the given <VAR>domain</VAR>. If <VAR>domain</VAR> is <CODE>NULL</CODE>, the default domain is used instead. To list the messages, use the function <CODE>po_next_message</CODE> repeatedly. </DL> </P> <P> <DL> <DT><U>Function:</U> void <B>po_message_iterator_free</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I> <DD><A NAME="IDX847"></A> The <CODE>po_message_iterator_free</CODE> function frees an iterator previously allocated through the <CODE>po_message_iterator</CODE> function. </DL> </P> <P> <DL> <DT><U>Function:</U> po_message_t <B>po_next_message</B> <I>(po_message_iterator_t <VAR>iterator</VAR>)</I> <DD><A NAME="IDX848"></A> The <CODE>po_next_message</CODE> function returns the next message from <VAR>iterator</VAR> and advances the iterator. It returns <CODE>NULL</CODE> when the iterator has reached the end of its message list. </DL> </P> <P> The following functions returns details of a <CODE>po_message_t</CODE>. Recall that the results are valid as long as the <VAR>file</VAR> handle is valid. </P> <P> <DL> <DT><U>Function:</U> const char * <B>po_message_msgid</B> <I>(po_message_t <VAR>message</VAR>)</I> <DD><A NAME="IDX849"></A> The <CODE>po_message_msgid</CODE> function returns the <CODE>msgid</CODE> (untranslated English string) of a message. This is guaranteed to be non-<CODE>NULL</CODE>. </DL> </P> <P> <DL> <DT><U>Function:</U> const char * <B>po_message_msgid_plural</B> <I>(po_message_t <VAR>message</VAR>)</I> <DD><A NAME="IDX850"></A> The <CODE>po_message_msgid_plural</CODE> function returns the <CODE>msgid_plural</CODE> (untranslated English plural string) of a message with plurals, or <CODE>NULL</CODE> for a message without plural. </DL> </P> <P> <DL> <DT><U>Function:</U> const char * <B>po_message_msgstr</B> <I>(po_message_t <VAR>message</VAR>)</I> <DD><A NAME="IDX851"></A> The <CODE>po_message_msgstr</CODE> function returns the <CODE>msgstr</CODE> (translation) of a message. For an untranslated message, the return value is an empty string. </DL> </P> <P> <DL> <DT><U>Function:</U> const char * <B>po_message_msgstr_plural</B> <I>(po_message_t <VAR>message</VAR>, int <VAR>index</VAR>)</I> <DD><A NAME="IDX852"></A> The <CODE>po_message_msgstr_plural</CODE> function returns the <CODE>msgstr[<VAR>index</VAR>]</CODE> of a message with plurals, or <CODE>NULL</CODE> when the <VAR>index</VAR> is out of range or for a message without plural. </DL> </P> <P> Here is an example code how these functions can be used. </P> <PRE> const char *filename = ...; po_file_t file = po_file_read (filename); if (file == NULL) error (EXIT_FAILURE, errno, "couldn't open the PO file %s", filename); { const char * const *domains = po_file_domains (file); const char * const *domainp; for (domainp = domains; *domainp; domainp++) { const char *domain = *domainp; po_message_iterator_t iterator = po_message_iterator (file, domain); for (;;) { po_message_t *message = po_next_message (iterator); if (message == NULL) break; { const char *msgid = po_message_msgid (message); const char *msgstr = po_message_msgstr (message); ... } } po_message_iterator_free (iterator); } } po_file_free (file); </PRE> <P><HR><P> Go to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_6.html">previous</A>, <A HREF="gettext_8.html">next</A>, <A HREF="gettext_22.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. </BODY> </HTML>