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 @vindex MSGFILTER_MSGCTXT@r{, environment variable}
  12 @vindex MSGFILTER_MSGID@r{, environment variable}
  13 @vindex MSGFILTER_MSGID_PLURAL@r{, environment variable}
  14 @vindex MSGFILTER_LOCATION@r{, environment variable}
  15 @vindex MSGFILTER_PLURAL_FORM@r{, environment variable}
  16 @vindex MSGFILTER_PREV_MSGCTXT@r{, environment variable}
  17 @vindex MSGFILTER_PREV_MSGID@r{, environment variable}
  18 @vindex MSGFILTER_PREV_MSGID_PLURAL@r{, environment variable}
  19 During each @var{filter} invocation, the environment variable
  20 @code{MSGFILTER_MSGID} is bound to the message's msgid, and the environment
  21 variable @code{MSGFILTER_LOCATION} is bound to the location in the PO file
  22 of the message.  If the message has a context, the environment variable
  23 @code{MSGFILTER_MSGCTXT} is bound to the message's msgctxt, otherwise it is
  24 unbound.  If the message has a plural form, environment variable
  25 @code{MSGFILTER_MSGID_PLURAL} is bound to the message's msgid_plural and
  26 @code{MSGFILTER_PLURAL_FORM} is bound to the order number of the plural
  27 actually processed (starting with 0), otherwise both are unbound.
  28 If the message has a previous msgid (added by @code{msgmerge}),
  29 environment variable @code{MSGFILTER_PREV_MSGCTXT} is bound to the
  30 message's previous msgctxt, @code{MSGFILTER_PREV_MSGID} is bound to
  31 the previous msgid, and @code{MSGFILTER_PREV_MSGID_PLURAL} is bound to
  32 the previous msgid_plural.
  33
  34 @subsection Input file location
  35
  36 @table @samp
  37 @item -i @var{inputfile}
  38 @itemx --input=@var{inputfile}
  39 @opindex -i@r{, @code{msgfilter} option}
  40 @opindex --input@r{, @code{msgfilter} option}
  41 Input PO file.
  42
  43 @item -D @var{directory}
  44 @itemx --directory=@var{directory}
  45 @opindex -D@r{, @code{msgfilter} option}
  46 @opindex --directory@r{, @code{msgfilter} option}
  47 Add @var{directory} to the list of directories.  Source files are
  48 searched relative to this list of directories.  The resulting @file{.po}
  49 file will be written relative to the current directory, though.
  50
  51 @end table
  52
  53 If no @var{inputfile} is given or if it is @samp{-}, standard input is read.
  54
  55 @subsection Output file location
  56
  57 @table @samp
  58 @item -o @var{file}
  59 @itemx --output-file=@var{file}
  60 @opindex -o@r{, @code{msgfilter} option}
  61 @opindex --output-file@r{, @code{msgfilter} option}
  62 Write output to specified file.
  63
  64 @end table
  65
  66 The results are written to standard output if no output file is specified
  67 or if it is @samp{-}.
  68
  69 @subsection The filter
  70
  71 The @var{filter} can be any program that reads a translation from standard
  72 input and writes a modified translation to standard output.  A frequently
  73 used filter is @samp{sed}.  A few particular built-in filters are also
  74 recognized.
  75
  76 @table @samp
  77 @item --newline
  78 @opindex --newline@r{, @code{msgfilter} option}
  79 Add newline at the end of each input line and also strip the ending
  80 newline from the output line.
  81
  82 @end table
  83
  84 @cindex @code{msgfilter} filter and catalog encoding
  85 Note: If the filter is not a built-in filter, you have to care about encodings:
  86 It is your responsibility to ensure that the @var{filter} can cope
  87 with input encoded in the translation catalog's encoding.  If the
  88 @var{filter} wants input in a particular encoding, you can in a first step
  89 convert the translation catalog to that encoding using the @samp{msgconv}
  90 program, before invoking @samp{msgfilter}.  If the @var{filter} wants input
  91 in the locale's encoding, but you want to avoid the locale's encoding, then
  92 you can first convert the translation catalog to UTF-8 using the
  93 @samp{msgconv} program and then make @samp{msgfilter} work in an UTF-8
  94 locale, by using the @code{LC_ALL} environment variable.
  95
  96 @cindex portability problems with @code{sed}
  97 Note: Most translations in a translation catalog don't end with a
  98 newline character.  For this reason, unless the @code{--newline}
  99 option is used, it is important that the @var{filter} recognizes its
 100 last input line even if it ends without a newline, and that it doesn't
 101 add an undesired trailing newline at the end.  The @samp{sed} program on
 102 some platforms is known to ignore the last line of input if it is not
 103 terminated with a newline.  You can use GNU @code{sed} instead; it does
 104 not have this limitation.
 105
 106 @subsection Useful @var{filter-option}s when the @var{filter} is @samp{sed}
 107
 108 @table @samp
 109 @item -e @var{script}
 110 @itemx --expression=@var{script}
 111 @opindex -e@r{, @code{msgfilter} option}
 112 @opindex --expression@r{, @code{msgfilter} option}
 113 Add @var{script} to the commands to be executed.
 114
 115 @item -f @var{scriptfile}
 116 @itemx --file=@var{scriptfile}
 117 @opindex -f@r{, @code{msgfilter} option}
 118 @opindex --file@r{, @code{msgfilter} option}
 119 Add the contents of @var{scriptfile} to the commands to be executed.
 120
 121 @item -n
 122 @itemx --quiet
 123 @itemx --silent
 124 @opindex -n@r{, @code{msgfilter} option}
 125 @opindex --quiet@r{, @code{msgfilter} option}
 126 @opindex --silent@r{, @code{msgfilter} option}
 127 Suppress automatic printing of pattern space.
 128
 129 @end table
 130
 131 @subsection Built-in @var{filter}s
 132
 133 @pindex recode-sr-latin
 134 @cindex @code{recode-sr-latin} program
 135 The filter @samp{recode-sr-latin} is recognized as a built-in filter.
 136 The command @samp{recode-sr-latin} converts Serbian text, written in the
 137 Cyrillic script, to the Latin script.
 138 The command @samp{msgfilter recode-sr-latin} applies this conversion to the
 139 translations of a PO file.  Thus, it can be used to convert an @file{sr.po}
 140 file to an @file{sr@@latin.po} file.
 141
 142 @pindex quot
 143 The filter @samp{quot} is recognized as a built-in filter.
 144 The command @samp{msgfilter quot} converts any quotations surrounded
 145 by a pair of @samp{"}, @samp{'}, and @samp{`}.
 146
 147 @pindex boldquot
 148 The filter @samp{boldquot} is recognized as a built-in filter.
 149 The command @samp{msgfilter boldquot} converts any quotations
 150 surrounded by a pair of @samp{"}, @samp{'}, and @samp{`}, also adding the
 151 VT100 escape sequences to the text to decorate it as bold.
 152
 153 The use of built-in filters is not sensitive to the current locale's encoding.
 154 Moreover, when used with a built-in filter, @samp{msgfilter} can automatically
 155 convert the message catalog to the UTF-8 encoding when needed.
 156
 157 @subsection Input file syntax
 158
 159 @table @samp
 160 @item -P
 161 @itemx --properties-input
 162 @opindex -P@r{, @code{msgfilter} option}
 163 @opindex --properties-input@r{, @code{msgfilter} option}
 164 Assume the input file is a Java ResourceBundle in Java @code{.properties}
 165 syntax, not in PO file syntax.
 166
 167 @item --stringtable-input
 168 @opindex --stringtable-input@r{, @code{msgfilter} option}
 169 Assume the input file is a NeXTstep/GNUstep localized resource file in
 170 @code{.strings} syntax, not in PO file syntax.
 171
 172 @end table
 173
 174 @subsection Output details
 175
 176 @c --no-escape and --escape omitted on purpose.  They are not useful.
 177
 178 @table @samp
 179 @item --color
 180 @itemx --color=@var{when}
 181 @opindex --color@r{, @code{msgfilter} option}
 182 Specify whether or when to use colors and other text attributes.
 183 See @ref{The --color option} for details.
 184
 185 @item --style=@var{style_file}
 186 @opindex --style@r{, @code{msgfilter} option}
 187 Specify the CSS style rule file to use for @code{--color}.
 188 See @ref{The --style option} for details.
 189
 190 @item --force-po
 191 @opindex --force-po@r{, @code{msgfilter} option}
 192 Always write an output file even if it contains no message.
 193
 194 @item --indent
 195 @opindex --indent@r{, @code{msgfilter} option}
 196 Write the .po file using indented style.
 197
 198 @item --keep-header
 199 @opindex --keep-header@r{, @code{msgfilter} option}
 200 Keep the header entry, i.e.@: the message with @samp{msgid ""}, unmodified,
 201 instead of filtering it.  By default, the header entry is subject to
 202 filtering like any other message.
 203
 204 @item --no-location
 205 @opindex --no-location@r{, @code{msgfilter} option}
 206 Do not write @samp{#: @var{filename}:@var{line}} lines.
 207
 208 @item -n
 209 @itemx --add-location=@var{type}
 210 @opindex --add-location@r{, @code{msgfilter} option}
 211 Generate @samp{#: @var{filename}:@var{line}} lines (default).
 212
 213 The optional @var{type} can be either @samp{full}, @samp{file}, or
 214 @samp{never}.  If it is not given or @samp{full}, it generates the
 215 lines with both file name and line number.  If it is @samp{file}, the
 216 line number part is omitted.  If it is @samp{never}, it completely
 217 suppresses the lines (same as @code{--no-location}).
 218
 219 @item --strict
 220 @opindex --strict@r{, @code{msgfilter} option}
 221 Write out a strict Uniforum conforming PO file.  Note that this
 222 Uniforum format should be avoided because it doesn't support the
 223 GNU extensions.
 224
 225 @item -p
 226 @itemx --properties-output
 227 @opindex -p@r{, @code{msgfilter} option}
 228 @opindex --properties-output@r{, @code{msgfilter} option}
 229 Write out a Java ResourceBundle in Java @code{.properties} syntax.  Note
 230 that this file format doesn't support plural forms and silently drops
 231 obsolete messages.
 232
 233 @item --stringtable-output
 234 @opindex --stringtable-output@r{, @code{msgfilter} option}
 235 Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax.
 236 Note that this file format doesn't support plural forms.
 237
 238 @item -w @var{number}
 239 @itemx --width=@var{number}
 240 @opindex -w@r{, @code{msgfilter} option}
 241 @opindex --width@r{, @code{msgfilter} option}
 242 Set the output page width.  Long strings in the output files will be
 243 split across multiple lines in order to ensure that each line's width
 244 (= number of screen columns) is less or equal to the given @var{number}.
 245
 246 @item --no-wrap
 247 @opindex --no-wrap@r{, @code{msgfilter} option}
 248 Do not break long message lines.  Message lines whose width exceeds the
 249 output page width will not be split into several lines.  Only file reference
 250 lines which are wider than the output page width will be split.
 251
 252 @item -s
 253 @itemx --sort-output
 254 @opindex -s@r{, @code{msgfilter} option}
 255 @opindex --sort-output@r{, @code{msgfilter} option}
 256 Generate sorted output.  Note that using this option makes it much harder
 257 for the translator to understand each message's context.
 258
 259 @item -F
 260 @itemx --sort-by-file
 261 @opindex -F@r{, @code{msgfilter} option}
 262 @opindex --sort-by-file@r{, @code{msgfilter} option}
 263 Sort output by file location.
 264
 265 @end table
 266
 267 @subsection Informative output
 268
 269 @table @samp
 270 @item -h
 271 @itemx --help
 272 @opindex -h@r{, @code{msgfilter} option}
 273 @opindex --help@r{, @code{msgfilter} option}
 274 Display this help and exit.
 275
 276 @item -V
 277 @itemx --version
 278 @opindex -V@r{, @code{msgfilter} option}
 279 @opindex --version@r{, @code{msgfilter} option}
 280 Output version information and exit.
 281
 282 @end table
 283
 284 @subsection Examples
 285
 286 To convert German translations to Swiss orthography (in an UTF-8 locale):
 287
 288 @smallexample
 289 msgconv -t UTF-8 de.po | msgfilter sed -e 's/@ss{}/ss/g'
 290 @end smallexample
 291
 292 To convert Serbian translations in Cyrillic script to Latin script:
 293
 294 @smallexample
 295 msgfilter recode-sr-latin < sr.po
 296 @end smallexample