gnu/dist/gettext/gettext-tools/doc/msgfmt.texi

   1 @pindex msgfmt
   2 @cindex @code{msgfmt} program, usage
   3 @example
   4 msgfmt [@var{option}] @var{filename}.po @dots{}
   5 @end example
   6
   7 @cindex generate binary message catalog from PO file
   8 The @code{msgfmt} programs generates a binary message catalog from a textual
   9 translation description.
  10
  11 @subsection Input file location
  12
  13 @table @samp
  14 @item @var{filename}.po @dots{}
  15
  16 @item -D @var{directory}
  17 @itemx --directory=@var{directory}
  18 @opindex -D@r{, @code{msgfmt} option}
  19 @opindex --directory@r{, @code{msgfmt} option}
  20 Add @var{directory} to the list of directories.  Source files are
  21 searched relative to this list of directories.  The resulting @file{.po}
  22 file will be written relative to the current directory, though.
  23
  24 @end table
  25
  26 If an input file is @samp{-}, standard input is read.
  27
  28 @subsection Operation mode
  29
  30 @table @samp
  31 @item -j
  32 @itemx --java
  33 @opindex -j@r{, @code{msgfmt} option}
  34 @opindex --java@r{, @code{msgfmt} option}
  35 @cindex Java mode, and @code{msgfmt} program
  36 Java mode: generate a Java @code{ResourceBundle} class.
  37
  38 @item --java2
  39 @opindex --java2@r{, @code{msgfmt} option}
  40 Like --java, and assume Java2 (JDK 1.2 or higher).
  41
  42 @item --csharp
  43 @opindex --csharp@r{, @code{msgfmt} option}
  44 @cindex C# mode, and @code{msgfmt} program
  45 C# mode: generate a .NET .dll file containing a subclass of
  46 @code{GettextResourceSet}.
  47
  48 @item --csharp-resources
  49 @opindex --csharp-resources@r{, @code{msgfmt} option}
  50 @cindex C# resources mode, and @code{msgfmt} program
  51 C# resources mode: generate a .NET @file{.resources} file.
  52
  53 @item --tcl
  54 @opindex --tcl@r{, @code{msgfmt} option}
  55 @cindex Tcl mode, and @code{msgfmt} program
  56 Tcl mode: generate a tcl/msgcat @file{.msg} file.
  57
  58 @item --qt
  59 @opindex --qt@r{, @code{msgfmt} option}
  60 @cindex Qt mode, and @code{msgfmt} program
  61 Qt mode: generate a Qt @file{.qm} file.
  62
  63 @end table
  64
  65 @subsection Output file location
  66
  67 @table @samp
  68 @item -o @var{file}
  69 @itemx --output-file=@var{file}
  70 @opindex -o@r{, @code{msgfmt} option}
  71 @opindex --output-file@r{, @code{msgfmt} option}
  72 Write output to specified file.
  73
  74 @item --strict
  75 @opindex --strict@r{, @code{msgfmt} option}
  76 Direct the program to work strictly following the Uniforum/Sun
  77 implementation.  Currently this only affects the naming of the output
  78 file.  If this option is not given the name of the output file is the
  79 same as the domain name.  If the strict Uniforum mode is enabled the
  80 suffix @file{.mo} is added to the file name if it is not already
  81 present.
  82
  83 We find this behaviour of Sun's implementation rather silly and so by
  84 default this mode is @emph{not} selected.
  85
  86 @end table
  87
  88 If the output @var{file} is @samp{-}, output is written to standard output.
  89
  90 @subsection Output file location in Java mode
  91
  92 @table @samp
  93 @item -r @var{resource}
  94 @itemx --resource=@var{resource}
  95 @opindex -r@r{, @code{msgfmt} option}
  96 @opindex --resource@r{, @code{msgfmt} option}
  97 Specify the resource name.
  98
  99 @item -l @var{locale}
 100 @itemx --locale=@var{locale}
 101 @opindex -l@r{, @code{msgfmt} option}
 102 @opindex --locale@r{, @code{msgfmt} option}
 103 Specify the locale name, either a language specification of the form @var{ll}
 104 or a combined language and country specification of the form @var{ll_CC}.
 105
 106 @item -d @var{directory}
 107 @opindex -d@r{, @code{msgfmt} option}
 108 Specify the base directory of classes directory hierarchy.
 109
 110 @end table
 111
 112 The class name is determined by appending the locale name to the resource name,
 113 separated with an underscore.  The @samp{-d} option is mandatory.  The class
 114 is written under the specified directory.
 115
 116 @subsection Output file location in C# mode
 117
 118 @table @samp
 119 @item -r @var{resource}
 120 @itemx --resource=@var{resource}
 121 @opindex -r@r{, @code{msgfmt} option}
 122 @opindex --resource@r{, @code{msgfmt} option}
 123 Specify the resource name.
 124
 125 @item -l @var{locale}
 126 @itemx --locale=@var{locale}
 127 @opindex -l@r{, @code{msgfmt} option}
 128 @opindex --locale@r{, @code{msgfmt} option}
 129 Specify the locale name, either a language specification of the form @var{ll}
 130 or a combined language and country specification of the form @var{ll_CC}.
 131
 132 @item -d @var{directory}
 133 @opindex -d@r{, @code{msgfmt} option}
 134 Specify the base directory for locale dependent @file{.dll} files.
 135
 136 @end table
 137
 138 The @samp{-l} and @samp{-d} options are mandatory.  The @file{.dll} file is
 139 written in a subdirectory of the specified directory whose name depends on the
 140 locale.
 141
 142 @subsection Output file location in Tcl mode
 143
 144 @table @samp
 145 @item -l @var{locale}
 146 @itemx --locale=@var{locale}
 147 @opindex -l@r{, @code{msgfmt} option}
 148 @opindex --locale@r{, @code{msgfmt} option}
 149 Specify the locale name, either a language specification of the form @var{ll}
 150 or a combined language and country specification of the form @var{ll_CC}.
 151
 152 @item -d @var{directory}
 153 @opindex -d@r{, @code{msgfmt} option}
 154 Specify the base directory of @file{.msg} message catalogs.
 155
 156 @end table
 157
 158 The @samp{-l} and @samp{-d} options are mandatory.  The @file{.msg} file is
 159 written in the specified directory.
 160
 161 @subsection Input file syntax
 162
 163 @table @samp
 164 @item -P
 165 @itemx --properties-input
 166 @opindex -P@r{, @code{msgfmt} option}
 167 @opindex --properties-input@r{, @code{msgfmt} option}
 168 Assume the input files are Java ResourceBundles in Java @code{.properties}
 169 syntax, not in PO file syntax.
 170
 171 @item --stringtable-input
 172 @opindex --stringtable-input@r{, @code{msgfmt} option}
 173 Assume the input files are NeXTstep/GNUstep localized resource files in
 174 @code{.strings} syntax, not in PO file syntax.
 175
 176 @end table
 177
 178 @subsection Input file interpretation
 179
 180 @table @samp
 181 @item -c
 182 @itemx --check
 183 @opindex -c@r{, @code{msgfmt} option}
 184 @opindex --check@r{, @code{msgfmt} option}
 185 Perform all the checks implied by @code{--check-format}, @code{--check-header},
 186 @code{--check-domain}.
 187
 188 @item --check-format
 189 @opindex --check-format@r{, @code{msgfmt} option}
 190 @cindex check format strings
 191 Check language dependent format strings.
 192
 193 If the string represents a format string used in a
 194 @code{printf}-like function both strings should have the same number of
 195 @samp{%} format specifiers, with matching types.  If the flag
 196 @code{c-format} or @code{possible-c-format} appears in the special
 197 comment @key{#,} for this entry a check is performed.  For example, the
 198 check will diagnose using @samp{%.*s} against @samp{%s}, or @samp{%d}
 199 against @samp{%s}, or @samp{%d} against @samp{%x}.  It can even handle
 200 positional parameters.
 201
 202 Normally the @code{xgettext} program automatically decides whether a
 203 string is a format string or not.  This algorithm is not perfect,
 204 though.  It might regard a string as a format string though it is not
 205 used in a @code{printf}-like function and so @code{msgfmt} might report
 206 errors where there are none.
 207
 208 To solve this problem the programmer can dictate the decision to the
 209 @code{xgettext} program (@pxref{c-format}).  The translator should not
 210 consider removing the flag from the @key{#,} line.  This "fix" would be
 211 reversed again as soon as @code{msgmerge} is called the next time.
 212
 213 @item --check-header
 214 @opindex --check-header@r{, @code{msgfmt} option}
 215 Verify presence and contents of the header entry.  @xref{Header Entry},
 216 for a description of the various fields in the header entry.
 217
 218 @item --check-domain
 219 @opindex --check-domain@r{, @code{msgfmt} option}
 220 Check for conflicts between domain directives and the @code{--output-file}
 221 option
 222
 223 @item -C
 224 @itemx --check-compatibility
 225 @opindex -C@r{, @code{msgfmt} option}
 226 @opindex --check-compatibility@r{, @code{msgfmt} option}
 227 @cindex compatibility with X/Open @code{msgfmt}
 228 Check that GNU msgfmt behaves like X/Open msgfmt.  This will give an error
 229 when attempting to use the GNU extensions.
 230
 231 @item --check-accelerators[=@var{char}]
 232 @opindex --check-accelerators@r{, @code{msgfmt} option}
 233 @cindex keyboard accelerator checking
 234 @cindex menu, keyboard accelerator support
 235 @cindex mnemonics of menu entries
 236 Check presence of keyboard accelerators for menu items.  This is based on
 237 the convention used in some GUIs that a keyboard accelerator in a menu
 238 item string is designated by an immediately preceding @samp{&} character.
 239 Sometimes a keyboard accelerator is also called "keyboard mnemonic".
 240 This check verifies that if the untranslated string has exactly one
 241 @samp{&} character, the translated string has exactly one @samp{&} as well.
 242 If this option is given with a @var{char} argument, this @var{char} should
 243 be a non-alphanumeric character and is used as keyboard accelerator mark
 244 instead of @samp{&}.
 245
 246 @item -f
 247 @itemx --use-fuzzy
 248 @opindex -f@r{, @code{msgfmt} option}
 249 @opindex --use-fuzzy@r{, @code{msgfmt} option}
 250 @cindex force use of fuzzy entries
 251 Use fuzzy entries in output.  Note that using this option is usually wrong,
 252 because fuzzy messages are exactly those which have not been validated by
 253 a human translator.
 254
 255 @end table
 256
 257 @subsection Output details
 258
 259 @table @samp
 260 @item -a @var{number}
 261 @itemx --alignment=@var{number}
 262 @opindex -a@r{, @code{msgfmt} option}
 263 @opindex --alignment@r{, @code{msgfmt} option}
 264 Align strings to @var{number} bytes (default: 1).
 265 @c Currently the README mentions that this constant could be changed by
 266 @c the installer by changing the value in config.h.  Should this go away?
 267
 268 @item --no-hash
 269 @opindex --no-hash@r{, @code{msgfmt} option}
 270 Don't include a hash table in the binary file.  Lookup will be more expensive
 271 at run time (binary search instead of hash table lookup).
 272
 273 @end table
 274
 275 @subsection Informative output
 276
 277 @table @samp
 278 @item -h
 279 @itemx --help
 280 @opindex -h@r{, @code{msgfmt} option}
 281 @opindex --help@r{, @code{msgfmt} option}
 282 Display this help and exit.
 283
 284 @item -V
 285 @itemx --version
 286 @opindex -V@r{, @code{msgfmt} option}
 287 @opindex --version@r{, @code{msgfmt} option}
 288 Output version information and exit.
 289
 290 @item --statistics
 291 @opindex --statistics@r{, @code{msgfmt} option}
 292 Print statistics about translations.
 293
 294 @item -v
 295 @itemx --verbose
 296 @opindex -v@r{, @code{msgfmt} option}
 297 @opindex --verbose@r{, @code{msgfmt} option}
 298 Increase verbosity level.
 299
 300 @end table