release/src/router/gettext/gettext-tools/doc/msgfilter.texi

   1 @pindex msgfilter
   2 @cindex @code{msgfilter} program, usage
   3 @example
   4 msgfilter [@var{option}] @var{filter} [@var{filter-option}]
   5 @end example
   6
   7 @cindex apply a filter to translations
   8 The @code{msgfilter} program applies a filter to all translations of a
   9 translation catalog.
  10
  11 @subsection Input file location
  12
  13 @table @samp
  14 @item -i @var{inputfile}
  15 @itemx --input=@var{inputfile}
  16 @opindex -i@r{, @code{msgfilter} option}
  17 @opindex --input@r{, @code{msgfilter} option}
  18 Input PO file.
  19
  20 @item -D @var{directory}
  21 @itemx --directory=@var{directory}
  22 @opindex -D@r{, @code{msgfilter} option}
  23 @opindex --directory@r{, @code{msgfilter} option}
  24 Add @var{directory} to the list of directories.  Source files are
  25 searched relative to this list of directories.  The resulting @file{.po}
  26 file will be written relative to the current directory, though.
  27
  28 @end table
  29
  30 If no @var{inputfile} is given or if it is @samp{-}, standard input is read.
  31
  32 @subsection Output file location
  33
  34 @table @samp
  35 @item -o @var{file}
  36 @itemx --output-file=@var{file}
  37 @opindex -o@r{, @code{msgfilter} option}
  38 @opindex --output-file@r{, @code{msgfilter} option}
  39 Write output to specified file.
  40
  41 @end table
  42
  43 The results are written to standard output if no output file is specified
  44 or if it is @samp{-}.
  45
  46 @subsection The filter
  47
  48 The @var{filter} can be any program that reads a translation from standard
  49 input and writes a modified translation to standard output.  A frequently
  50 used filter is @samp{sed}.
  51
  52 @cindex @code{msgfilter} filter and catalog encoding
  53 Note: It is your responsibility to ensure that the @var{filter} can cope
  54 with input encoded in the translation catalog's encoding.  If the
  55 @var{filter} wants input in a particular encoding, you can in a first step
  56 convert the translation catalog to that encoding using the @samp{msgconv}
  57 program, before invoking @samp{msgfilter}.  If the @var{filter} wants input
  58 in the locale's encoding, but you want to avoid the locale's encoding, then
  59 you can first convert the translation catalog to UTF-8 using the
  60 @samp{msgconv} program and then make @samp{msgfilter} work in an UTF-8
  61 locale, by using the @code{LC_ALL} environment variable.
  62
  63 @cindex portability problems with @code{sed}
  64 Note: Most translations in a translation catalog don't end with a newline
  65 character.  For this reason, it is important that the @var{filter}
  66 recognizes its last input line even if it ends without a newline, and that
  67 it doesn't add an undesired trailing newline at the end.  The @samp{sed}
  68 program on some platforms is known to ignore the last line of input if it
  69 is not terminated with a newline.  You can use GNU @code{sed} instead; it
  70 does not have this limitation.
  71
  72 @subsection Useful @var{filter-option}s when the @var{filter} is @samp{sed}
  73
  74 @table @samp
  75 @item -e @var{script}
  76 @itemx --expression=@var{script}
  77 @opindex -e@r{, @code{msgfilter} option}
  78 @opindex --expression@r{, @code{msgfilter} option}
  79 Add @var{script} to the commands to be executed.
  80
  81 @item -f @var{scriptfile}
  82 @itemx --file=@var{scriptfile}
  83 @opindex -f@r{, @code{msgfilter} option}
  84 @opindex --file@r{, @code{msgfilter} option}
  85 Add the contents of @var{scriptfile} to the commands to be executed.
  86
  87 @item -n
  88 @itemx --quiet
  89 @itemx --silent
  90 @opindex -n@r{, @code{msgfilter} option}
  91 @opindex --quiet@r{, @code{msgfilter} option}
  92 @opindex --silent@r{, @code{msgfilter} option}
  93 Suppress automatic printing of pattern space.
  94
  95 @end table
  96
  97 @subsection Input file syntax
  98
  99 @table @samp
 100 @item -P
 101 @itemx --properties-input
 102 @opindex -P@r{, @code{msgfilter} option}
 103 @opindex --properties-input@r{, @code{msgfilter} option}
 104 Assume the input file is a Java ResourceBundle in Java @code{.properties}
 105 syntax, not in PO file syntax.
 106
 107 @item --stringtable-input
 108 @opindex --stringtable-input@r{, @code{msgfilter} option}
 109 Assume the input file is a NeXTstep/GNUstep localized resource file in
 110 @code{.strings} syntax, not in PO file syntax.
 111
 112 @end table
 113
 114 @subsection Output details
 115
 116 @c --no-escape and --escape omitted on purpose.  They are not useful.
 117
 118 @table @samp
 119 @item --force-po
 120 @opindex --force-po@r{, @code{msgfilter} option}
 121 Always write an output file even if it contains no message.
 122
 123 @item --indent
 124 @opindex --indent@r{, @code{msgfilter} option}
 125 Write the .po file using indented style.
 126
 127 @item --keep-header
 128 @opindex --keep-header@r{, @code{msgfilter} option}
 129 Keep the header entry, i.e. the message with @samp{msgid ""}, unmodified,
 130 instead of filtering it.  By default, the header entry is subject to
 131 filtering like any other message.
 132
 133 @item --no-location
 134 @opindex --no-location@r{, @code{msgfilter} option}
 135 Do not write @samp{#: @var{filename}:@var{line}} lines.
 136
 137 @item --add-location
 138 @opindex --add-location@r{, @code{msgfilter} option}
 139 Generate @samp{#: @var{filename}:@var{line}} lines (default).
 140
 141 @item --strict
 142 @opindex --strict@r{, @code{msgfilter} option}
 143 Write out a strict Uniforum conforming PO file.  Note that this
 144 Uniforum format should be avoided because it doesn't support the
 145 GNU extensions.
 146
 147 @item -p
 148 @itemx --properties-output
 149 @opindex -p@r{, @code{msgfilter} option}
 150 @opindex --properties-output@r{, @code{msgfilter} option}
 151 Write out a Java ResourceBundle in Java @code{.properties} syntax.  Note
 152 that this file format doesn't support plural forms and silently drops
 153 obsolete messages.
 154
 155 @item --stringtable-output
 156 @opindex --stringtable-output@r{, @code{msgfilter} option}
 157 Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax.
 158 Note that this file format doesn't support plural forms.
 159
 160 @item -w @var{number}
 161 @itemx --width=@var{number}
 162 @opindex -w@r{, @code{msgfilter} option}
 163 @opindex --width@r{, @code{msgfilter} option}
 164 Set the output page width.  Long strings in the output files will be
 165 split across multiple lines in order to ensure that each line's width
 166 (= number of screen columns) is less or equal to the given @var{number}.
 167
 168 @item --no-wrap
 169 @opindex --no-wrap@r{, @code{msgfilter} option}
 170 Do not break long message lines.  Message lines whose width exceeds the
 171 output page width will not be split into several lines.  Only file reference
 172 lines which are wider than the output page width will be split.
 173
 174 @item -s
 175 @itemx --sort-output
 176 @opindex -s@r{, @code{msgfilter} option}
 177 @opindex --sort-output@r{, @code{msgfilter} option}
 178 Generate sorted output.  Note that using this option makes it much harder
 179 for the translator to understand each message's context.
 180
 181 @item -F
 182 @itemx --sort-by-file
 183 @opindex -F@r{, @code{msgfilter} option}
 184 @opindex --sort-by-file@r{, @code{msgfilter} option}
 185 Sort output by file location.
 186
 187 @end table
 188
 189 @subsection Informative output
 190
 191 @table @samp
 192 @item -h
 193 @itemx --help
 194 @opindex -h@r{, @code{msgfilter} option}
 195 @opindex --help@r{, @code{msgfilter} option}
 196 Display this help and exit.
 197
 198 @item -V
 199 @itemx --version
 200 @opindex -V@r{, @code{msgfilter} option}
 201 @opindex --version@r{, @code{msgfilter} option}
 202 Output version information and exit.
 203
 204 @end table