diff options
Diffstat (limited to 'gettext-tools/doc/msgfmt.texi')
-rw-r--r-- | gettext-tools/doc/msgfmt.texi | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/gettext-tools/doc/msgfmt.texi b/gettext-tools/doc/msgfmt.texi new file mode 100644 index 0000000..402bc1a --- /dev/null +++ b/gettext-tools/doc/msgfmt.texi @@ -0,0 +1,377 @@ +@pindex msgfmt +@cindex @code{msgfmt} program, usage +@example +msgfmt [@var{option}] @var{filename}.po @dots{} +@end example + +@cindex generate binary message catalog from PO file +The @code{msgfmt} programs generates a binary message catalog from a textual +translation description. + +@subsection Input file location + +@table @samp +@item @var{filename}.po @dots{} + +@item -D @var{directory} +@itemx --directory=@var{directory} +@opindex -D@r{, @code{msgfmt} option} +@opindex --directory@r{, @code{msgfmt} option} +Add @var{directory} to the list of directories. Source files are +searched relative to this list of directories. The resulting binary +file will be written relative to the current directory, though. + +@end table + +If an input file is @samp{-}, standard input is read. + +@subsection Operation mode + +@table @samp +@item -j +@itemx --java +@opindex -j@r{, @code{msgfmt} option} +@opindex --java@r{, @code{msgfmt} option} +@cindex Java mode, and @code{msgfmt} program +Java mode: generate a Java @code{ResourceBundle} class. + +@item --java2 +@opindex --java2@r{, @code{msgfmt} option} +Like --java, and assume Java2 (JDK 1.2 or higher). + +@item --csharp +@opindex --csharp@r{, @code{msgfmt} option} +@cindex C# mode, and @code{msgfmt} program +C# mode: generate a .NET .dll file containing a subclass of +@code{GettextResourceSet}. + +@item --csharp-resources +@opindex --csharp-resources@r{, @code{msgfmt} option} +@cindex C# resources mode, and @code{msgfmt} program +C# resources mode: generate a .NET @file{.resources} file. + +@item --tcl +@opindex --tcl@r{, @code{msgfmt} option} +@cindex Tcl mode, and @code{msgfmt} program +Tcl mode: generate a tcl/msgcat @file{.msg} file. + +@item --qt +@opindex --qt@r{, @code{msgfmt} option} +@cindex Qt mode, and @code{msgfmt} program +Qt mode: generate a Qt @file{.qm} file. + +@item --desktop +@opindex --desktop@r{, @code{msgfmt} option} +@cindex Desktop Entry mode, and @code{msgfmt} program +Desktop Entry mode: generate a @file{.desktop} file. + +@end table + +@subsection Output file location + +@table @samp +@item -o @var{file} +@itemx --output-file=@var{file} +@opindex -o@r{, @code{msgfmt} option} +@opindex --output-file@r{, @code{msgfmt} option} +Write output to specified file. + +@item --strict +@opindex --strict@r{, @code{msgfmt} option} +Direct the program to work strictly following the Uniforum/Sun +implementation. Currently this only affects the naming of the output +file. If this option is not given the name of the output file is the +same as the domain name. If the strict Uniforum mode is enabled the +suffix @file{.mo} is added to the file name if it is not already +present. + +We find this behaviour of Sun's implementation rather silly and so by +default this mode is @emph{not} selected. + +@end table + +If the output @var{file} is @samp{-}, output is written to standard output. + +@subsection Output file location in Java mode + +@table @samp +@item -r @var{resource} +@itemx --resource=@var{resource} +@opindex -r@r{, @code{msgfmt} option} +@opindex --resource@r{, @code{msgfmt} option} +Specify the resource name. + +@item -l @var{locale} +@itemx --locale=@var{locale} +@opindex -l@r{, @code{msgfmt} option} +@opindex --locale@r{, @code{msgfmt} option} +Specify the locale name, either a language specification of the form @var{ll} +or a combined language and country specification of the form @var{ll_CC}. + +@item -d @var{directory} +@opindex -d@r{, @code{msgfmt} option} +Specify the base directory of classes directory hierarchy. + +@item --source +@opindex --source@r{, @code{msgfmt} option} +Produce a .java source file, instead of a compiled .class file. + +@end table + +The class name is determined by appending the locale name to the resource name, +separated with an underscore. The @samp{-d} option is mandatory. The class +is written under the specified directory. + +@subsection Output file location in C# mode + +@table @samp +@item -r @var{resource} +@itemx --resource=@var{resource} +@opindex -r@r{, @code{msgfmt} option} +@opindex --resource@r{, @code{msgfmt} option} +Specify the resource name. + +@item -l @var{locale} +@itemx --locale=@var{locale} +@opindex -l@r{, @code{msgfmt} option} +@opindex --locale@r{, @code{msgfmt} option} +Specify the locale name, either a language specification of the form @var{ll} +or a combined language and country specification of the form @var{ll_CC}. + +@item -d @var{directory} +@opindex -d@r{, @code{msgfmt} option} +Specify the base directory for locale dependent @file{.dll} files. + +@end table + +The @samp{-l} and @samp{-d} options are mandatory. The @file{.dll} file is +written in a subdirectory of the specified directory whose name depends on the +locale. + +@subsection Output file location in Tcl mode + +@table @samp +@item -l @var{locale} +@itemx --locale=@var{locale} +@opindex -l@r{, @code{msgfmt} option} +@opindex --locale@r{, @code{msgfmt} option} +Specify the locale name, either a language specification of the form @var{ll} +or a combined language and country specification of the form @var{ll_CC}. + +@item -d @var{directory} +@opindex -d@r{, @code{msgfmt} option} +Specify the base directory of @file{.msg} message catalogs. + +@end table + +The @samp{-l} and @samp{-d} options are mandatory. The @file{.msg} file is +written in the specified directory. + +@subsection Desktop Entry mode operations + +@table @samp +@item --template=@var{template} +@opindex --template@r{, @code{msgfmt} option} +Specify a .desktop file used as a template. + +@item -k[@var{keywordspec}] +@itemx --keyword[=@var{keywordspec}] +@opindex -k@r{, @code{msgfmt} option} +@opindex --keyword@r{, @code{msgfmt} option} +Specify @var{keywordspec} as an additional keyword to be looked for. +Without a @var{keywordspec}, the option means to not use default keywords. + +@item -l @var{locale} +@itemx --locale=@var{locale} +@opindex -l@r{, @code{msgfmt} option} +@opindex --locale@r{, @code{msgfmt} option} +Specify the locale name, either a language specification of the form @var{ll} +or a combined language and country specification of the form @var{ll_CC}. + +@item -d @var{directory} +@opindex -d@r{, @code{msgfmt} option} +Specify the base directory of @file{.msg} message catalogs. + +@end table + +To generate a @samp{.desktop} file for a single locale, you can use it +as follows. + +@example +msgfmt --desktop --template=@var{template} --locale=@var{locale} \ + -o @var{file} @var{filename}.po @dots{} +@end example + +On the other hand, when using msgfmt from a Makefile, it is cumbersome +to loop over all locales under a particular directory. msgfmt +provides a special operation mode for this use-case. To generate a +@samp{.desktop} file from multiple @samp{.po} files under a directory, +specify the directory with the @samp{-d} option. + +@example +msgfmt --desktop --template=@var{template} -d @var{directory} -o @var{file} +@end example + +msgfmt first reads the @samp{LINGUAS} file under @var{directory}, and +then processes all @samp{.po} files listed there. You can also limit +the locales to a subset, through the @samp{LINGUAS} environment +variable. + +For either operation modes, the @samp{-o} and @samp{--template} +options are mandatory. + +@subsection Input file syntax + +@table @samp +@item -P +@itemx --properties-input +@opindex -P@r{, @code{msgfmt} option} +@opindex --properties-input@r{, @code{msgfmt} option} +Assume the input files are Java ResourceBundles in Java @code{.properties} +syntax, not in PO file syntax. + +@item --stringtable-input +@opindex --stringtable-input@r{, @code{msgfmt} option} +Assume the input files are NeXTstep/GNUstep localized resource files in +@code{.strings} syntax, not in PO file syntax. + +@end table + +@subsection Input file interpretation + +@table @samp +@item -c +@itemx --check +@opindex -c@r{, @code{msgfmt} option} +@opindex --check@r{, @code{msgfmt} option} +Perform all the checks implied by @code{--check-format}, @code{--check-header}, +@code{--check-domain}. + +@item --check-format +@opindex --check-format@r{, @code{msgfmt} option} +@cindex check format strings +Check language dependent format strings. + +If the string represents a format string used in a +@code{printf}-like function both strings should have the same number of +@samp{%} format specifiers, with matching types. If the flag +@code{c-format} or @code{possible-c-format} appears in the special +comment @key{#,} for this entry a check is performed. For example, the +check will diagnose using @samp{%.*s} against @samp{%s}, or @samp{%d} +against @samp{%s}, or @samp{%d} against @samp{%x}. It can even handle +positional parameters. + +Normally the @code{xgettext} program automatically decides whether a +string is a format string or not. This algorithm is not perfect, +though. It might regard a string as a format string though it is not +used in a @code{printf}-like function and so @code{msgfmt} might report +errors where there are none. + +To solve this problem the programmer can dictate the decision to the +@code{xgettext} program (@pxref{c-format}). The translator should not +consider removing the flag from the @key{#,} line. This "fix" would be +reversed again as soon as @code{msgmerge} is called the next time. + +@item --check-header +@opindex --check-header@r{, @code{msgfmt} option} +Verify presence and contents of the header entry. @xref{Header Entry}, +for a description of the various fields in the header entry. + +@item --check-domain +@opindex --check-domain@r{, @code{msgfmt} option} +Check for conflicts between domain directives and the @code{--output-file} +option + +@item -C +@itemx --check-compatibility +@opindex -C@r{, @code{msgfmt} option} +@opindex --check-compatibility@r{, @code{msgfmt} option} +@cindex compatibility with X/Open @code{msgfmt} +Check that GNU msgfmt behaves like X/Open msgfmt. This will give an error +when attempting to use the GNU extensions. + +@item --check-accelerators[=@var{char}] +@opindex --check-accelerators@r{, @code{msgfmt} option} +@cindex keyboard accelerator checking +@cindex menu, keyboard accelerator support +@cindex mnemonics of menu entries +Check presence of keyboard accelerators for menu items. This is based on +the convention used in some GUIs that a keyboard accelerator in a menu +item string is designated by an immediately preceding @samp{&} character. +Sometimes a keyboard accelerator is also called "keyboard mnemonic". +This check verifies that if the untranslated string has exactly one +@samp{&} character, the translated string has exactly one @samp{&} as well. +If this option is given with a @var{char} argument, this @var{char} should +be a non-alphanumeric character and is used as keyboard accelerator mark +instead of @samp{&}. + +@item -f +@itemx --use-fuzzy +@opindex -f@r{, @code{msgfmt} option} +@opindex --use-fuzzy@r{, @code{msgfmt} option} +@cindex force use of fuzzy entries +Use fuzzy entries in output. Note that using this option is usually wrong, +because fuzzy messages are exactly those which have not been validated by +a human translator. + +@end table + +@subsection Output details + +@table @samp +@item -a @var{number} +@itemx --alignment=@var{number} +@opindex -a@r{, @code{msgfmt} option} +@opindex --alignment@r{, @code{msgfmt} option} +Align strings to @var{number} bytes (default: 1). +@c Currently the README mentions that this constant could be changed by +@c the installer by changing the value in config.h. Should this go away? + +@item --endianness=@var{byteorder} +@opindex --endianness@r{, @code{msgfmt} option} +Write out 32-bit numbers in the given byte order. The possible values are +@code{big} and @code{little}. The default depends on the platform, namely +on the endianness of the CPU. + +MO files of any endianness can be used on any platform. When a MO file has +an endianness other than the platform's one, the 32-bit numbers from the MO +file are swapped at runtime. The performance impact is negligible. + +This option can be useful to produce MO files that are independent of the +platform. + +@item --no-hash +@opindex --no-hash@r{, @code{msgfmt} option} +Don't include a hash table in the binary file. Lookup will be more expensive +at run time (binary search instead of hash table lookup). + +@end table + +@subsection Informative output + +@table @samp +@item -h +@itemx --help +@opindex -h@r{, @code{msgfmt} option} +@opindex --help@r{, @code{msgfmt} option} +Display this help and exit. + +@item -V +@itemx --version +@opindex -V@r{, @code{msgfmt} option} +@opindex --version@r{, @code{msgfmt} option} +Output version information and exit. + +@item --statistics +@opindex --statistics@r{, @code{msgfmt} option} +Print statistics about translations. When the option @code{--verbose} is used +in combination with @code{--statistics}, the input file name is printed in +front of the statistics line. + +@item -v +@itemx --verbose +@opindex -v@r{, @code{msgfmt} option} +@opindex --verbose@r{, @code{msgfmt} option} +Increase verbosity level. + +@end table |