gettext: msgfilter Invocation
1
1 9.4 Invoking the ‘msgfilter’ Program
1 ====================================
1
1 msgfilter [OPTION] FILTER [FILTER-OPTION]
1
1 The ‘msgfilter’ program applies a filter to all translations of a
1 translation catalog.
1
1 During each FILTER invocation, the environment variable
1 ‘MSGFILTER_MSGID’ is bound to the message’s msgid, and the environment
1 variable ‘MSGFILTER_LOCATION’ is bound to the location in the PO file of
1 the message. If the message has a context, the environment variable
1 ‘MSGFILTER_MSGCTXT’ is bound to the message’s msgctxt, otherwise it is
1 unbound. If the message has a plural form, environment variable
1 ‘MSGFILTER_MSGID_PLURAL’ is bound to the message’s msgid_plural and
1 ‘MSGFILTER_PLURAL_FORM’ is bound to the order number of the plural
1 actually processed (starting with 0), otherwise both are unbound. If
1 the message has a previous msgid (added by ‘msgmerge’), environment
1 variable ‘MSGFILTER_PREV_MSGCTXT’ is bound to the message’s previous
1 msgctxt, ‘MSGFILTER_PREV_MSGID’ is bound to the previous msgid, and
1 ‘MSGFILTER_PREV_MSGID_PLURAL’ is bound to the previous msgid_plural.
1
1 9.4.1 Input file location
1 -------------------------
1
1 ‘-i INPUTFILE’
1 ‘--input=INPUTFILE’
1 Input PO file.
1
1 ‘-D DIRECTORY’
1 ‘--directory=DIRECTORY’
1 Add DIRECTORY to the list of directories. Source files are
1 searched relative to this list of directories. The resulting ‘.po’
1 file will be written relative to the current directory, though.
1
1 If no INPUTFILE is given or if it is ‘-’, standard input is read.
1
1 9.4.2 Output file location
1 --------------------------
1
1 ‘-o FILE’
1 ‘--output-file=FILE’
1 Write output to specified file.
1
1 The results are written to standard output if no output file is
1 specified or if it is ‘-’.
1
1 9.4.3 The filter
1 ----------------
1
1 The FILTER can be any program that reads a translation from standard
1 input and writes a modified translation to standard output. A
1 frequently used filter is ‘sed’. A few particular built-in filters are
1 also recognized.
1
1 ‘--newline’
1 Add newline at the end of each input line and also strip the ending
1 newline from the output line.
1
1 Note: If the filter is not a built-in filter, you have to care about
1 encodings: It is your responsibility to ensure that the FILTER can cope
1 with input encoded in the translation catalog’s encoding. If the FILTER
1 wants input in a particular encoding, you can in a first step convert
1 the translation catalog to that encoding using the ‘msgconv’ program,
1 before invoking ‘msgfilter’. If the FILTER wants input in the locale’s
1 encoding, but you want to avoid the locale’s encoding, then you can
1 first convert the translation catalog to UTF-8 using the ‘msgconv’
1 program and then make ‘msgfilter’ work in an UTF-8 locale, by using the
1 ‘LC_ALL’ environment variable.
1
1 Note: Most translations in a translation catalog don’t end with a
1 newline character. For this reason, unless the ‘--newline’ option is
1 used, it is important that the FILTER recognizes its last input line
1 even if it ends without a newline, and that it doesn’t add an undesired
1 trailing newline at the end. The ‘sed’ program on some platforms is
1 known to ignore the last line of input if it is not terminated with a
1 newline. You can use GNU ‘sed’ instead; it does not have this
1 limitation.
1
1 9.4.4 Useful FILTER-OPTIONs when the FILTER is ‘sed’
1 ----------------------------------------------------
1
1 ‘-e SCRIPT’
1 ‘--expression=SCRIPT’
1 Add SCRIPT to the commands to be executed.
1
1 ‘-f SCRIPTFILE’
1 ‘--file=SCRIPTFILE’
1 Add the contents of SCRIPTFILE to the commands to be executed.
1
1 ‘-n’
1 ‘--quiet’
1 ‘--silent’
1 Suppress automatic printing of pattern space.
1
1 9.4.5 Built-in FILTERs
1 ----------------------
1
1 The filter ‘recode-sr-latin’ is recognized as a built-in filter. The
1 command ‘recode-sr-latin’ converts Serbian text, written in the Cyrillic
1 script, to the Latin script. The command ‘msgfilter recode-sr-latin’
1 applies this conversion to the translations of a PO file. Thus, it can
1 be used to convert an ‘sr.po’ file to an ‘sr@latin.po’ file.
1
1 The filter ‘quot’ is recognized as a built-in filter. The command
1 ‘msgfilter quot’ converts any quotations surrounded by a pair of ‘"’,
1 ‘'’, and ‘`’.
1
1 The filter ‘boldquot’ is recognized as a built-in filter. The
1 command ‘msgfilter boldquot’ converts any quotations surrounded by a
1 pair of ‘"’, ‘'’, and ‘`’, also adding the VT100 escape sequences to the
1 text to decorate it as bold.
1
1 The use of built-in filters is not sensitive to the current locale’s
1 encoding. Moreover, when used with a built-in filter, ‘msgfilter’ can
1 automatically convert the message catalog to the UTF-8 encoding when
1 needed.
1
1 9.4.6 Input file syntax
1 -----------------------
1
1 ‘-P’
1 ‘--properties-input’
1 Assume the input file is a Java ResourceBundle in Java
1 ‘.properties’ syntax, not in PO file syntax.
1
1 ‘--stringtable-input’
1 Assume the input file is a NeXTstep/GNUstep localized resource file
1 in ‘.strings’ syntax, not in PO file syntax.
1
1 9.4.7 Output details
1 --------------------
1
1 ‘--color’
1 ‘--color=WHEN’
1 Specify whether or when to use colors and other text attributes.
1 See ⇒The --color option for details.
1
1 ‘--style=STYLE_FILE’
11 Specify the CSS style rule file to use for ‘--color’. See ⇒
The --style option for details.
1
1 ‘--force-po’
1 Always write an output file even if it contains no message.
1
1 ‘--indent’
1 Write the .po file using indented style.
1
1 ‘--keep-header’
1 Keep the header entry, i.e. the message with ‘msgid ""’,
1 unmodified, instead of filtering it. By default, the header entry
1 is subject to filtering like any other message.
1
1 ‘--no-location’
1 Do not write ‘#: FILENAME:LINE’ lines.
1
1 ‘-n’
1 ‘--add-location=TYPE’
1 Generate ‘#: FILENAME:LINE’ lines (default).
1
1 The optional TYPE can be either ‘full’, ‘file’, or ‘never’. If it
1 is not given or ‘full’, it generates the lines with both file name
1 and line number. If it is ‘file’, the line number part is omitted.
1 If it is ‘never’, it completely suppresses the lines (same as
1 ‘--no-location’).
1
1 ‘--strict’
1 Write out a strict Uniforum conforming PO file. Note that this
1 Uniforum format should be avoided because it doesn’t support the
1 GNU extensions.
1
1 ‘-p’
1 ‘--properties-output’
1 Write out a Java ResourceBundle in Java ‘.properties’ syntax. Note
1 that this file format doesn’t support plural forms and silently
1 drops obsolete messages.
1
1 ‘--stringtable-output’
1 Write out a NeXTstep/GNUstep localized resource file in ‘.strings’
1 syntax. Note that this file format doesn’t support plural forms.
1
1 ‘-w NUMBER’
1 ‘--width=NUMBER’
1 Set the output page width. Long strings in the output files will
1 be split across multiple lines in order to ensure that each line’s
1 width (= number of screen columns) is less or equal to the given
1 NUMBER.
1
1 ‘--no-wrap’
1 Do not break long message lines. Message lines whose width exceeds
1 the output page width will not be split into several lines. Only
1 file reference lines which are wider than the output page width
1 will be split.
1
1 ‘-s’
1 ‘--sort-output’
1 Generate sorted output. Note that using this option makes it much
1 harder for the translator to understand each message’s context.
1
1 ‘-F’
1 ‘--sort-by-file’
1 Sort output by file location.
1
1 9.4.8 Informative output
1 ------------------------
1
1 ‘-h’
1 ‘--help’
1 Display this help and exit.
1
1 ‘-V’
1 ‘--version’
1 Output version information and exit.
1
1 9.4.9 Examples
1 --------------
1
1 To convert German translations to Swiss orthography (in an UTF-8
1 locale):
1
1 msgconv -t UTF-8 de.po | msgfilter sed -e 's/ß/ss/g'
1
1 To convert Serbian translations in Cyrillic script to Latin script:
1
1 msgfilter recode-sr-latin < sr.po
1