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{msgmerge} 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 -n
 192 @itemx --add-location=@var{type}
 193 @opindex --add-location@r{, @code{msgmerge} option}
 194 Generate @samp{#: @var{filename}:@var{line}} lines (default).
 195
 196 The optional @var{type} can be either @samp{full}, @samp{file}, or
 197 @samp{never}.  If it is not given or @samp{full}, it generates the
 198 lines with both file name and line number.  If it is @samp{file}, the
 199 line number part is omitted.  If it is @samp{never}, it completely
 200 suppresses the lines (same as @code{--no-location}).
 201
 202 @item --strict
 203 @opindex --strict@r{, @code{msgmerge} option}
 204 Write out a strict Uniforum conforming PO file.  Note that this
 205 Uniforum format should be avoided because it doesn't support the
 206 GNU extensions.
 207
 208 @item -p
 209 @itemx --properties-output
 210 @opindex -p@r{, @code{msgmerge} option}
 211 @opindex --properties-output@r{, @code{msgmerge} option}
 212 Write out a Java ResourceBundle in Java @code{.properties} syntax.  Note
 213 that this file format doesn't support plural forms and silently drops
 214 obsolete messages.
 215
 216 @item --stringtable-output
 217 @opindex --stringtable-output@r{, @code{msgmerge} option}
 218 Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax.
 219 Note that this file format doesn't support plural forms.
 220
 221 @item -w @var{number}
 222 @itemx --width=@var{number}
 223 @opindex -w@r{, @code{msgmerge} option}
 224 @opindex --width@r{, @code{msgmerge} option}
 225 Set the output page width.  Long strings in the output files will be
 226 split across multiple lines in order to ensure that each line's width
 227 (= number of screen columns) is less or equal to the given @var{number}.
 228
 229 @item --no-wrap
 230 @opindex --no-wrap@r{, @code{msgmerge} option}
 231 Do not break long message lines.  Message lines whose width exceeds the
 232 output page width will not be split into several lines.  Only file reference
 233 lines which are wider than the output page width will be split.
 234
 235 @item -s
 236 @itemx --sort-output
 237 @opindex -s@r{, @code{msgmerge} option}
 238 @opindex --sort-output@r{, @code{msgmerge} option}
 239 @cindex sorting @code{msgmerge} output
 240 Generate sorted output.  Note that using this option makes it much harder
 241 for the translator to understand each message's context.
 242
 243 @item -F
 244 @itemx --sort-by-file
 245 @opindex -F@r{, @code{msgmerge} option}
 246 @opindex --sort-by-file@r{, @code{msgmerge} option}
 247 Sort output by file location.
 248
 249 @end table
 250
 251 @subsection Informative output
 252
 253 @table @samp
 254 @item -h
 255 @itemx --help
 256 @opindex -h@r{, @code{msgmerge} option}
 257 @opindex --help@r{, @code{msgmerge} option}
 258 Display this help and exit.
 259
 260 @item -V
 261 @itemx --version
 262 @opindex -V@r{, @code{msgmerge} option}
 263 @opindex --version@r{, @code{msgmerge} option}
 264 Output version information and exit.
 265
 266 @item -v
 267 @itemx --verbose
 268 @opindex -v@r{, @code{msgmerge} option}
 269 @opindex --verbose@r{, @code{msgmerge} option}
 270 Increase verbosity level.
 271
 272 @item -q
 273 @itemx --quiet
 274 @itemx --silent
 275 @opindex -q@r{, @code{msgmerge} option}
 276 @opindex --quiet@r{, @code{msgmerge} option}
 277 @opindex --silent@r{, @code{msgmerge} option}
 278 Suppress progress indicators.
 279
 280 @end table