| @c This file is part of the GNU gettext manual. |
| @c Copyright (C) 1995-2019 Free Software Foundation, Inc. |
| @c See the file gettext.texi for copying conditions. |
| |
| @pindex msgfilter |
| @cindex @code{msgfilter} program, usage |
| @example |
| msgfilter [@var{option}] @var{filter} [@var{filter-option}] |
| @end example |
| |
| @cindex apply a filter to translations |
| The @code{msgfilter} program applies a filter to all translations of a |
| translation catalog. |
| |
| @vindex MSGFILTER_MSGCTXT@r{, environment variable} |
| @vindex MSGFILTER_MSGID@r{, environment variable} |
| @vindex MSGFILTER_MSGID_PLURAL@r{, environment variable} |
| @vindex MSGFILTER_LOCATION@r{, environment variable} |
| @vindex MSGFILTER_PLURAL_FORM@r{, environment variable} |
| @vindex MSGFILTER_PREV_MSGCTXT@r{, environment variable} |
| @vindex MSGFILTER_PREV_MSGID@r{, environment variable} |
| @vindex MSGFILTER_PREV_MSGID_PLURAL@r{, environment variable} |
| During each @var{filter} invocation, the environment variable |
| @code{MSGFILTER_MSGID} is bound to the message's msgid, and the environment |
| variable @code{MSGFILTER_LOCATION} is bound to the location in the PO file |
| of the message. If the message has a context, the environment variable |
| @code{MSGFILTER_MSGCTXT} is bound to the message's msgctxt, otherwise it is |
| unbound. If the message has a plural form, environment variable |
| @code{MSGFILTER_MSGID_PLURAL} is bound to the message's msgid_plural and |
| @code{MSGFILTER_PLURAL_FORM} is bound to the order number of the plural |
| actually processed (starting with 0), otherwise both are unbound. |
| If the message has a previous msgid (added by @code{msgmerge}), |
| environment variable @code{MSGFILTER_PREV_MSGCTXT} is bound to the |
| message's previous msgctxt, @code{MSGFILTER_PREV_MSGID} is bound to |
| the previous msgid, and @code{MSGFILTER_PREV_MSGID_PLURAL} is bound to |
| the previous msgid_plural. |
| |
| @subsection Input file location |
| |
| @table @samp |
| @item -i @var{inputfile} |
| @itemx --input=@var{inputfile} |
| @opindex -i@r{, @code{msgfilter} option} |
| @opindex --input@r{, @code{msgfilter} option} |
| Input PO file. |
| |
| @item -D @var{directory} |
| @itemx --directory=@var{directory} |
| @opindex -D@r{, @code{msgfilter} option} |
| @opindex --directory@r{, @code{msgfilter} option} |
| Add @var{directory} to the list of directories. Source files are |
| searched relative to this list of directories. The resulting @file{.po} |
| file will be written relative to the current directory, though. |
| |
| @end table |
| |
| If no @var{inputfile} is given or if it is @samp{-}, standard input is read. |
| |
| @subsection Output file location |
| |
| @table @samp |
| @item -o @var{file} |
| @itemx --output-file=@var{file} |
| @opindex -o@r{, @code{msgfilter} option} |
| @opindex --output-file@r{, @code{msgfilter} option} |
| Write output to specified file. |
| |
| @end table |
| |
| The results are written to standard output if no output file is specified |
| or if it is @samp{-}. |
| |
| @subsection The filter |
| |
| The @var{filter} 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}. A few particular built-in filters are also |
| recognized. |
| |
| @table @samp |
| @item --newline |
| @opindex --newline@r{, @code{msgfilter} option} |
| Add newline at the end of each input line and also strip the ending |
| newline from the output line. |
| |
| @end table |
| |
| @cindex @code{msgfilter} filter and catalog encoding |
| Note: If the filter is not a built-in filter, you have to care about encodings: |
| It is your responsibility to ensure that the @var{filter} can cope |
| with input encoded in the translation catalog's encoding. If the |
| @var{filter} wants input in a particular encoding, you can in a first step |
| convert the translation catalog to that encoding using the @samp{msgconv} |
| program, before invoking @samp{msgfilter}. If the @var{filter} 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} program and then make @samp{msgfilter} work in an UTF-8 |
| locale, by using the @code{LC_ALL} environment variable. |
| |
| @cindex portability problems with @code{sed} |
| Note: Most translations in a translation catalog don't end with a |
| newline character. For this reason, unless the @code{--newline} |
| option is used, it is important that the @var{filter} 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} 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} instead; it does |
| not have this limitation. |
| |
| @subsection Useful @var{filter-option}s when the @var{filter} is @samp{sed} |
| |
| @table @samp |
| @item -e @var{script} |
| @itemx --expression=@var{script} |
| @opindex -e@r{, @code{msgfilter} option} |
| @opindex --expression@r{, @code{msgfilter} option} |
| Add @var{script} to the commands to be executed. |
| |
| @item -f @var{scriptfile} |
| @itemx --file=@var{scriptfile} |
| @opindex -f@r{, @code{msgfilter} option} |
| @opindex --file@r{, @code{msgfilter} option} |
| Add the contents of @var{scriptfile} to the commands to be executed. |
| |
| @item -n |
| @itemx --quiet |
| @itemx --silent |
| @opindex -n@r{, @code{msgfilter} option} |
| @opindex --quiet@r{, @code{msgfilter} option} |
| @opindex --silent@r{, @code{msgfilter} option} |
| Suppress automatic printing of pattern space. |
| |
| @end table |
| |
| @subsection Built-in @var{filter}s |
| |
| @pindex recode-sr-latin |
| @cindex @code{recode-sr-latin} program |
| The filter @samp{recode-sr-latin} is recognized as a built-in filter. |
| The command @samp{recode-sr-latin} converts Serbian text, written in the |
| Cyrillic script, to the Latin script. |
| The command @samp{msgfilter recode-sr-latin} applies this conversion to the |
| translations of a PO file. Thus, it can be used to convert an @file{sr.po} |
| file to an @file{sr@@latin.po} file. |
| |
| @pindex quot |
| The filter @samp{quot} is recognized as a built-in filter. |
| The command @samp{msgfilter quot} converts any quotations surrounded |
| by a pair of @samp{"}, @samp{'}, and @samp{`}. |
| |
| @pindex boldquot |
| The filter @samp{boldquot} is recognized as a built-in filter. |
| The command @samp{msgfilter boldquot} converts any quotations |
| surrounded by a pair of @samp{"}, @samp{'}, and @samp{`}, also adding the |
| VT100 escape sequences to the text to decorate it as bold. |
| |
| The use of built-in filters is not sensitive to the current locale's encoding. |
| Moreover, when used with a built-in filter, @samp{msgfilter} can automatically |
| convert the message catalog to the UTF-8 encoding when needed. |
| |
| @subsection Input file syntax |
| |
| @table @samp |
| @item -P |
| @itemx --properties-input |
| @opindex -P@r{, @code{msgfilter} option} |
| @opindex --properties-input@r{, @code{msgfilter} option} |
| Assume the input file is a Java ResourceBundle in Java @code{.properties} |
| syntax, not in PO file syntax. |
| |
| @item --stringtable-input |
| @opindex --stringtable-input@r{, @code{msgfilter} option} |
| Assume the input file is a NeXTstep/GNUstep localized resource file in |
| @code{.strings} syntax, not in PO file syntax. |
| |
| @end table |
| |
| @subsection Output details |
| |
| @c --no-escape and --escape omitted on purpose. They are not useful. |
| |
| @table @samp |
| @item --color |
| @itemx --color=@var{when} |
| @opindex --color@r{, @code{msgfilter} option} |
| Specify whether or when to use colors and other text attributes. |
| See @ref{The --color option} for details. |
| |
| @item --style=@var{style_file} |
| @opindex --style@r{, @code{msgfilter} option} |
| Specify the CSS style rule file to use for @code{--color}. |
| See @ref{The --style option} for details. |
| |
| @item --force-po |
| @opindex --force-po@r{, @code{msgfilter} option} |
| Always write an output file even if it contains no message. |
| |
| @item --indent |
| @opindex --indent@r{, @code{msgfilter} option} |
| Write the .po file using indented style. |
| |
| @item --keep-header |
| @opindex --keep-header@r{, @code{msgfilter} option} |
| Keep the header entry, i.e.@: the message with @samp{msgid ""}, unmodified, |
| instead of filtering it. By default, the header entry is subject to |
| filtering like any other message. |
| |
| @item --no-location |
| @opindex --no-location@r{, @code{msgfilter} option} |
| Do not write @samp{#: @var{filename}:@var{line}} lines. |
| |
| @item -n |
| @itemx --add-location=@var{type} |
| @opindex --add-location@r{, @code{msgfilter} option} |
| Generate @samp{#: @var{filename}:@var{line}} lines (default). |
| |
| The optional @var{type} can be either @samp{full}, @samp{file}, or |
| @samp{never}. If it is not given or @samp{full}, it generates the |
| lines with both file name and line number. If it is @samp{file}, the |
| line number part is omitted. If it is @samp{never}, it completely |
| suppresses the lines (same as @code{--no-location}). |
| |
| @item --strict |
| @opindex --strict@r{, @code{msgfilter} option} |
| Write out a strict Uniforum conforming PO file. Note that this |
| Uniforum format should be avoided because it doesn't support the |
| GNU extensions. |
| |
| @item -p |
| @itemx --properties-output |
| @opindex -p@r{, @code{msgfilter} option} |
| @opindex --properties-output@r{, @code{msgfilter} option} |
| Write out a Java ResourceBundle in Java @code{.properties} syntax. Note |
| that this file format doesn't support plural forms and silently drops |
| obsolete messages. |
| |
| @item --stringtable-output |
| @opindex --stringtable-output@r{, @code{msgfilter} option} |
| Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax. |
| Note that this file format doesn't support plural forms. |
| |
| @item -w @var{number} |
| @itemx --width=@var{number} |
| @opindex -w@r{, @code{msgfilter} option} |
| @opindex --width@r{, @code{msgfilter} option} |
| 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}. |
| |
| @item --no-wrap |
| @opindex --no-wrap@r{, @code{msgfilter} option} |
| 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. |
| |
| @item -s |
| @itemx --sort-output |
| @opindex -s@r{, @code{msgfilter} option} |
| @opindex --sort-output@r{, @code{msgfilter} option} |
| Generate sorted output. Note that using this option makes it much harder |
| for the translator to understand each message's context. |
| |
| @item -F |
| @itemx --sort-by-file |
| @opindex -F@r{, @code{msgfilter} option} |
| @opindex --sort-by-file@r{, @code{msgfilter} option} |
| Sort output by file location. |
| |
| @end table |
| |
| @subsection Informative output |
| |
| @table @samp |
| @item -h |
| @itemx --help |
| @opindex -h@r{, @code{msgfilter} option} |
| @opindex --help@r{, @code{msgfilter} option} |
| Display this help and exit. |
| |
| @item -V |
| @itemx --version |
| @opindex -V@r{, @code{msgfilter} option} |
| @opindex --version@r{, @code{msgfilter} option} |
| Output version information and exit. |
| |
| @end table |
| |
| @subsection Examples |
| |
| To convert German translations to Swiss orthography (in an UTF-8 locale): |
| |
| @smallexample |
| msgconv -t UTF-8 de.po | msgfilter sed -e 's/@ss{}/ss/g' |
| @end smallexample |
| |
| To convert Serbian translations in Cyrillic script to Latin script: |
| |
| @smallexample |
| msgfilter recode-sr-latin < sr.po |
| @end smallexample |