Tribblix: manual page: msgfmt.1

MSGFMT(1) User Commands MSGFMT(1)

NAME

msgfmt - create a message object from a message file

SYNOPSIS

msgfmt [-D dir | --directory=dir]
[-f | --use-fuzzy] [-g]
[-o output-file | --output-file=output-file]
[-s] [--strict] [-v] [--verbose] filename.po...

DESCRIPTION

The msgfmt utility creates message object files from portable object
files (filename.po), without changing the portable object files.

The .po file contains messages displayed to users by system commands
or by application programs. .po files can be edited. The messages in
these files can be rewritten in any language supported by the system.

The xgettext(1) command can be used to create .po files from script
or programs.

msgfmt interprets data as characters according to the current setting
of the LC_CTYPE locale category or according to the codeset specified
in the .po file.

OPTIONS

The following options are supported:

-D dir
--directory=dir
Adds dir to the list for input files
search.

-f
--use-fuzzy
Uses fuzzy entries in output. If this
option is not specified, fuzzy entries are
not included into the output. These
options are ignored if Solaris message
catalogs are processed.

-g
Directs the utility to generate the GNU-
compatible message catalog file. This
option cannot be specified with the -s
option.

-o output-file
--output=output-file
Specifies the output file name as output-
file. All domain directives and duplicate
msgids in the .po file are ignored.

-s
Directs the utility to generate the
Solaris message catalog file. This option
cannot be specified with the -g option.

--strict
Directs the utility to append the suffix
.mo to the generating message object file
name if it doesn't have this suffix. This
option is ignored if Solaris message
catalogs are processed.

-v
--verbose
Verbose. Lists duplicate message
identifiers if Solaris message catalog
files are processed. Message strings are
not redefined.

If GNU-compatible message files are
processed, this option detects and
diagnoses input file anomalies which might
represent translation errors. The msgid
and msgstr strings are studied and
compared. It is considered abnormal if one
string starts or ends with a newline while
the other does not. Also, if the string
represents a format string used in a
printf-like function, both strings should
have the same number of % format
specifiers, with matching types. If the
flag c-format appears in the special
comment '#' for this entry, a check is
performed.

USAGE

The format of portable object files (.po files) is defined as
follows. Each .po file contains one or more lines, with each line
containing either a comment or a statement. Comments start the line
with a pound sign (#) and end with the newline character. All
comments (except special comments described later) and empty lines
are ignored. The format of a statement is:

directive value

Each directive starts at the beginning of the line and is separated
from value by white space (such as one or more space or tab
characters). value consists of one or more quoted strings separated
by white space. Use any of the following types of directives for the
Solaris message file:

domain domainname
msgid message_identifier
msgstr message_string

For a GNU-compatible message file, use any of the following types of
directives:

domain domainname
msgid message_identifier
msgid_plural untranslated_string_plural
msgstr message_string
msgstr[n] message_string

The behavior of the domain directive is affected by the options used.
See OPTIONS for the behavior when the -o or --output-file options are
specified. If the -o or --output-file options are not specified, the
behavior of the domain directive is as follows:

o All msgids from the beginning of each .po file to the
first domain directive are put into a default message
object file. The default message object file is named
messages.mo, if the Solaris message catalog file format is
used to generate the message object file or if the
--strict option is specified. Otherwise, the default
message object file is named messages.

o When msgfmt encounters a domain domainname directive in
the .po file, all following msgids until the next domain
directive are put into the message object file, named
domainname.mo, if the Solaris message catalog file format
is used to generate the message object file or if the
--strict option is specified. Otherwise, the msgids are
put into the message object file named domainname.

o Duplicate msgids are defined in the scope of each domain.
That is, a msgid is considered a duplicate only if the
identical msgid exists in the same domain.

o All duplicate msgids are ignored.

The msgid directive specifies the value of a message identifier
associated with the directive that follows it. The msgid_plural
directive specifies the plural form message specified to the plural
message handling functions ngettext(), dngettext(), or dcngettext().
The message_identifier string identifies a target string to be used
at retrieval time. Each statement containing a msgid directive must
be followed by a statement containing a msgstr directive or msgstr[n]
directives.

The msgstr directive specifies the target string associated with the
message_identifier string declared in the immediately preceding msgid
directive.

The directive msgstr[n] (where n = 0, 1, 2, ...) specifies the target
string to be used with plural form handling functions ngettext(),
dngettext(), and dcngettext().

Message strings can contain the escape sequences \n for newline, \t
for tab, \v for vertical tab, \b for backspace, \r for carriage
return, \f for formfeed, \ for backslash, \" for double quote, \a for
alarm, \ddd for octal bit pattern, and \xDD for hexadecimal bit
pattern.

Comments for a GNU-compatible message file should be in one of the
following formats (the msgfmt utility will ignore these comments when
processing Solaris message files):

# translator-comments
#. automatic-comments
#: reference...
#, flag...

The '#:' comments indicate the location of the msgid string in the
source files in filename:line format. The '#', '#.', and '#:'
comments are informative only and are silently ignored by the msgfmt
utility. The '#,' comments require one or more flags separated by the
comma character. The following flags can be specified:

fuzzy
This flag can be inserted by the translator. It shows
that the msgstr string might not be a correct
translation (anymore). Only the translator can judge
if the translation requires further modification or is
acceptable as is. Once satisfied with the
translation, the translator removes this fuzzy flag.
If this flag is specified, the msgfmt utility will not
generate the entry for the immediately following msgid
in the output message catalog.

c-format
no-c-format
The c-format flag indicates that the msgid string is
used as a format string by printf-like functions. In
case the c-format flag is given for a string, the
msgfmt utility does some more tests to check the
validity of the translation.

In the GNU-compatible message file, the msgid entry with empty string
("") is called the header entry and treated specially. If the message
string for the header entry contains nplurals=value, the value
indicates the number of plural forms. For example, if nplurals=4,
there are four plural forms. If nplurals is defined, the same line
should contain plural=expression, separated by a semicolon character.
The expression is a C language expression to determine which version
of msgstr[n] is to be used based on the value of n, the last argument
of ngettext(), dngettext(), or dcngettext(). For example,

nplurals=2; plural= n == 1 ? 0 : 1

indicates that there are two plural forms in the language. msgstr[0]
is used if n == 1, otherwise msgstr[1] is used. For another example:

nplurals=3; plural= n == 1 ? 0 : n == 2 ? 1 : 2

indicates that there are three plural forms in the language.
msgstr[0] is used if n == 1, msgstr[1] is used if n == 2, otherwise
msgstr[2] is used.

If the header entry contains a charset=codeset string, the codeset is
used to indicate the codeset to be used to encode the message
strings. If the output string's codeset is different from the message
string's codeset, codeset conversion from the message string's
codeset to the output string's codeset will be performed upon the
call of gettext(), dgettext(), dcgettext(), ngettext(), dngettext(),
and dcngettext() for the GNU-compatible message catalogs. The output
string's codeset is determined by the current locale's codeset (the
return value of nl_langinfo(CODESET)) by default, and can be changed
by the call of bind_textdomain_codeset().

Message catalog file format

The msgfmt utility can generate the message object both in Solaris
message catalog file format and in GNU-compatible message catalog
file format. If the -s option is specified and the input file is a
Solaris .po file, the msgfmt utility generates the message object in
Solaris message catalog file format. If the -g option is specified
and the input file is a GNU .po file, the msgfmt utility generates
the message object in GNU-compatible message catalog file format. If
neither the -s nor -g option is specified, the msgfmt utility
determines the message catalog file format as follows:

o If the .po file contains a valid GNU header entry (having
an empty string for msgid), the msgfmt utility uses the
GNU-compatible message catalog file format.

o Otherwise, the msgfmt utility uses the Solaris message
catalog file format.

If the msgfmt utility determined that the Solaris message catalog
file format is used, as above, but found the .po file contains
directives that are specific to the GNU-compatible message catalog
file format, such as msgid_plural and msgstr[n], the msgfmt utility
handles those directives as invalid specifications.

EXAMPLES

Example 1: Creating message objects from message files

In this example, module1.po and module2.po are portable message
objects files.

example% cat module1.po
# default domain "messages.mo"
msgid "msg 1"
msgstr "msg 1 translation"
#
domain "help_domain"
msgid "help 2"
msgstr "help 2 translation"
#
domain "error_domain"
msgid "error 3"
msgstr "error 3 translation"
example% cat module2.po
# default domain "messages.mo"
msgid "mesg 4"
msgstr "mesg 4 translation"
#
domain "error_domain"
msgid "error 5"
msgstr "error 5 translation"
#
domain "window_domain"
msgid "window 6"
msgstr "window 6 translation"

The following command will produce the output files messages.mo,
help_domain.mo, and error_domain.mo in Solaris message catalog file
format:

example% msgfmt module1.po

The following command will produce the output files messages.mo,
help_domain.mo, error_domain.mo, and window_domain.mo in Solaris
message catalog file format:

example% msgfmt module1.po module2.po

The following command will produce the output file hello.mo in
Solaris message catalog file format:

example% msgfmt -o hello.mo module1.po module2.po

ENVIRONMENT VARIABLES

See environ(7) for descriptions of the following environmental
variables that affect the execution of msgfmt: LC_CTYPE, LC_MESSAGES,
and NLSPATH.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:

+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|CSI | Enabled |
+---------------+-----------------+

NOTES

Installing message catalogs under the C locale is pointless, since
they are ignored for the sake of efficiency.

May 21, 2022 MSGFMT(1)