gettext-tools/doc/msgmerge.texi

   1 @pindex msgmerge
   2 @cindex @code{msgmerge} program, usage
   3 @example
   4 msgmerge [@var{option}] @var{def}.po @var{ref}.pot
   5 @end example
   6
   7 The @code{msgmerge} program merges two Uniforum style .po files together.
   8 The @var{def}.po file is an existing PO file with translations which will
   9 be taken over to the newly created file as long as they still match;
  10 comments will be preserved, but extracted comments and file positions will
  11 be discarded.  The @var{ref}.pot file is the last created PO file with
  12 up-to-date source references but old translations, or a PO Template file
  13 (generally created by @code{xgettext}); any translations or comments
  14 in the file will be discarded, however dot comments and file positions
  15 will be preserved.  Where an exact match cannot be found, fuzzy matching
  16 is used to produce better results.
  17
  18 @subsection Input file location
  19
  20 @table @samp
  21 @item @var{def}.po
  22 Translations referring to old sources.
  23
  24 @item @var{ref}.pot
  25 References to the new sources.
  26
  27 @item -D @var{directory}
  28 @itemx --directory=@var{directory}
  29 @opindex -D@r{, @code{msgmerge} option}
  30 @opindex --directory@r{, @code{msgmerge} option}
  31 Add @var{directory} to the list of directories.  Source files are
  32 searched relative to this list of directories.  The resulting @file{.po}
  33 file will be written relative to the current directory, though.
  34
  35 @item -C @var{file}
  36 @itemx --compendium=@var{file}
  37 @opindex -C@r{, @code{msgmerge} option}
  38 @opindex --compendium@r{, @code{msgmerge} option}
  39 Specify an additional library of message translations.  @xref{Compendium}.
  40 This option may be specified more than once.
  41
  42 @end table
  43
  44 @subsection Operation mode
  45
  46 @table @samp
  47 @item -U
  48 @itemx --update
  49 @opindex -U@r{, @code{msgmerge} option}
  50 @opindex --update@r{, @code{msgmerge} option}
  51 Update @var{def}.po.  Do nothing if @var{def}.po is already up to date.
  52
  53 @end table
  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{msgmerge} option}
  61 @opindex --output-file@r{, @code{msgmerge} option}
  62 Write output to specified file.
  63
  64 @end table
  65
  66 @cindex standard output, and @code{msgmerge} program
  67 The results are written to standard output if no output file is specified
  68 or if it is @samp{-}.
  69
  70 @subsection Output file location in update mode
  71
  72 The result is written back to @var{def}.po.
  73
  74 @table @samp
  75 @item --backup=@var{control}
  76 @opindex --backup@r{, @code{msgmerge} option}
  77 @cindex backup old file, and @code{msgmerge} program
  78 Make a backup of @var{def}.po
  79
  80 @item --suffix=@var{suffix}
  81 @opindex --suffix@r{, @code{msgmerge} option}
  82 Override the usual backup suffix.
  83
  84 @end table
  85
  86 @cindex version control for backup files, @code{msgmerge}
  87 The version control method may be selected via the @code{--backup} option
  88 or through the @code{VERSION_CONTROL} environment variable.  Here are the
  89 values:
  90
  91 @table @samp
  92 @item none
  93 @itemx off
  94 Never make backups (even if @code{--backup} is given).
  95
  96 @item numbered
  97 @itemx t
  98 Make numbered backups.
  99
 100 @item existing
 101 @itemx nil
 102 Make numbered backups if numbered backups for this file already exist,
 103 otherwise make simple backups.
 104
 105 @item simple
 106 @itemx never
 107 Always make simple backups.
 108
 109 @end table
 110
 111 The backup suffix is @samp{~}, unless set with @code{--suffix} or the
 112 @code{SIMPLE_BACKUP_SUFFIX} environment variable.
 113
 114 @subsection Operation modifiers
 115
 116 @table @samp
 117 @item -m
 118 @itemx --multi-domain
 119 @opindex -m@r{, @code{msgmerge} option}
 120 @opindex --multi-domain@r{, @code{msgmerge} option}
 121 Apply @var{ref}.pot to each of the domains in @var{def}.po.
 122
 123 @item -N
 124 @itemx --no-fuzzy-matching
 125 @opindex -N@r{, @code{msgmerge} option}
 126 @opindex --no-fuzzy-matching@r{, @code{msgmerge} option}
 127 Do not use fuzzy matching when an exact match is not found.  This may speed
 128 up the operation considerably.
 129
 130 @item --previous
 131 @opindex --previous@r{, @code{msgmerge} option}
 132 Keep the previous msgids of translated messages, marked with @samp{#|}, when
 133 adding the fuzzy marker to such messages.
 134 @end table
 135
 136 @subsection Input file syntax
 137
 138 @table @samp
 139 @item -P
 140 @itemx --properties-input
 141 @opindex -P@r{, @code{msgmerge} option}
 142 @opindex --properties-input@r{, @code{msgmerge} option}
 143 Assume the input files are Java ResourceBundles in Java @code{.properties}
 144 syntax, not in PO file syntax.
 145
 146 @item --stringtable-input
 147 @opindex --stringtable-input@r{, @code{msgmerge} option}
 148 Assume the input files are NeXTstep/GNUstep localized resource files in
 149 @code{.strings} syntax, not in PO file syntax.
 150
 151 @end table
 152
 153 @subsection Output details
 154
 155 @c --no-escape and --escape omitted on purpose.  They are not useful.
 156
 157 @table @samp
 158 @item --lang=@var{catalogname}
 159 @opindex --lang@r{, @code{msgcat} option}
 160 Specify the @samp{Language} field to be used in the header entry.  See
 161 @ref{Header Entry} for the meaning of this field.  Note: The
 162 @samp{Language-Team} and @samp{Plural-Forms} fields are left unchanged.
 163 If this option is not specified, the @samp{Language} field is inferred, as
 164 best as possible, from the @samp{Language-Team} field.
 165
 166 @item --color
 167 @itemx --color=@var{when}
 168 @opindex --color@r{, @code{msgmerge} option}
 169 Specify whether or when to use colors and other text attributes.
 170 See @ref{The --color option} for details.
 171
 172 @item --style=@var{style_file}
 173 @opindex --style@r{, @code{msgmerge} option}
 174 Specify the CSS style rule file to use for @code{--color}.
 175 See @ref{The --style option} for details.
 176
 177 @item --force-po
 178 @opindex --force-po@r{, @code{msgmerge} option}
 179 Always write an output file even if it contains no message.
 180
 181 @item -i
 182 @itemx --indent
 183 @opindex -i@r{, @code{msgmerge} option}
 184 @opindex --indent@r{, @code{msgmerge} option}
 185 Write the .po file using indented style.
 186
 187 @item --no-location
 188 @opindex --no-location@r{, @code{msgmerge} option}
 189 Do not write @samp{#: @var{filename}:@var{line}} lines.
 190
 191 @item --add-location
 192 @opindex --add-location@r{, @code{msgmerge} option}
 193 Generate @samp{#: @var{filename}:@var{line}} lines (default).
 194
 195 @item --strict
 196 @opindex --strict@r{, @code{msgmerge} option}
 197 Write out a strict Uniforum conforming PO file.  Note that this
 198 Uniforum format should be avoided because it doesn't support the
 199 GNU extensions.
 200
 201 @item -p
 202 @itemx --properties-output
 203 @opindex -p@r{, @code{msgmerge} option}
 204 @opindex --properties-output@r{, @code{msgmerge} option}
 205 Write out a Java ResourceBundle in Java @code{.properties} syntax.  Note
 206 that this file format doesn't support plural forms and silently drops
 207 obsolete messages.
 208
 209 @item --stringtable-output
 210 @opindex --stringtable-output@r{, @code{msgmerge} option}
 211 Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax.
 212 Note that this file format doesn't support plural forms.
 213
 214 @item -w @var{number}
 215 @itemx --width=@var{number}
 216 @opindex -w@r{, @code{msgmerge} option}
 217 @opindex --width@r{, @code{msgmerge} option}
 218 Set the output page width.  Long strings in the output files will be
 219 split across multiple lines in order to ensure that each line's width
 220 (= number of screen columns) is less or equal to the given @var{number}.
 221
 222 @item --no-wrap
 223 @opindex --no-wrap@r{, @code{msgmerge} option}
 224 Do not break long message lines.  Message lines whose width exceeds the
 225 output page width will not be split into several lines.  Only file reference
 226 lines which are wider than the output page width will be split.
 227
 228 @item -s
 229 @itemx --sort-output
 230 @opindex -s@r{, @code{msgmerge} option}
 231 @opindex --sort-output@r{, @code{msgmerge} option}
 232 @cindex sorting @code{msgmerge} output
 233 Generate sorted output.  Note that using this option makes it much harder
 234 for the translator to understand each message's context.
 235
 236 @item -F
 237 @itemx --sort-by-file
 238 @opindex -F@r{, @code{msgmerge} option}
 239 @opindex --sort-by-file@r{, @code{msgmerge} option}
 240 Sort output by file location.
 241
 242 @end table
 243
 244 @subsection Informative output
 245
 246 @table @samp
 247 @item -h
 248 @itemx --help
 249 @opindex -h@r{, @code{msgmerge} option}
 250 @opindex --help@r{, @code{msgmerge} option}
 251 Display this help and exit.
 252
 253 @item -V
 254 @itemx --version
 255 @opindex -V@r{, @code{msgmerge} option}
 256 @opindex --version@r{, @code{msgmerge} option}
 257 Output version information and exit.
 258
 259 @item -v
 260 @itemx --verbose
 261 @opindex -v@r{, @code{msgmerge} option}
 262 @opindex --verbose@r{, @code{msgmerge} option}
 263 Increase verbosity level.
 264
 265 @item -q
 266 @itemx --quiet
 267 @itemx --silent
 268 @opindex -q@r{, @code{msgmerge} option}
 269 @opindex --quiet@r{, @code{msgmerge} option}
 270 @opindex --silent@r{, @code{msgmerge} option}
 271 Suppress progress indicators.
 272
 273 @end table