msgfmt

Name

msgfmt -- create a message object from a message file

Synopsis

msgfmt [options...] filename...

Description

The msgfmt command generates a binary message catalog from a textual translation description. Message catalogs, or message object files, are stored in files with a .mo extension.

Note: The format of message object files is not guaranteed to be portable. Message catalogs should always be generated on the target architecture using the msgfmt command.

The source message files, otherwise known as portable object files, have a .po extension.

The filename operands shall be portable object files. The .po file contains messages to be displayed to users by system utilities or by application programs. The portable object files are text files, and the messages in them can be rewritten in any language supported by the system.

If any filename is -, a portable object file shall be read from the standard input.

The msgfmt command interprets data as characters according to the current setting of the LC_CTYPE locale category.

Options

-c, --check

Detect and diagnose input file anomalies which might represent translation errors. The msgid and msgstr strings are studied and compared. It is considered abnormal that one string starts or ends with a newline while the other does not.

If the message is flagged as c-format (see Comment Handling), check that the msgid string and the msgstr translation have the same number of % format specifiers, with matching types.

-D directory, --directory=directory

Add directory to list for input files search. If filename is not an absolute pathname and filename cannot be opened, search for it in directory. This option may be repeated. Directories shall be searched in order, with the leftmost directory searched first.

-f, --use-fuzzy

Use entries marked as fuzzy in output. If this option is not specified, such entries are not included into the output. See Comment Handling below.

-o output-file, --output-file=output-file

Specify the output file name as output-file. If multiple domains or duplicate msgids in the .po file are present, the behavior is unspecified. If output-file is -, output is written to standard output.

--strict

Ensure that all output files have a .mo extension. Output files are named either by the -o (or --output-file) option, or by domains found in the input files.

-v, --verbose

Print additional information to the standard error, including the number of translated strings processed.

Operands

The filename operands are treated as portable object files. The format of portable object files is defined in EXTENDED DESCRIPTION.

Standard Input

The standard input is not used unless a filename operand is specified as "-".

Environment Variables

LANGUAGE 

Specifies one or more locale names.

LANG 

Specifies locale name.

LC_ALL 

Specifies locale name for all categories. If defined, overrides LANG, LC_CTYPE and LC_MESSAGES.

LC_CTYPE 

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments and input files).

LC_MESSAGES 

Specifies messaging locale, and if present overrides LANG for messages.

Standard Output

The standard output is not used unless the option-argument of the -o option is specified as -.

Extended Description

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 hash mark (#) and end with the newline character. Empty lines, or lines containing only white-space, shall be ignored. Comments can in certain circumstances alter the behavior of msgfmt. See Comment Handling below for details on comment processing. 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). The value consists of one or more quoted strings separated by white space. If two or more strings are specified as value, they are normalized into single string using the string normalization syntax specified in ISO C (1999). The following directives are supported:

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 option is specified. If the -o option is not specified, the behavior of the domain directive is as follows:

  1. All msgids from the beginning of each .po file to the first domain directive are put into a default message object file, messages (or messages.mo if the --strict option is specified).

  2. 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 domainname (or domainname.mo if --strict option is specified).

  3. 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.

  4. 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 shall 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 msgstr[n] (where n = 0, 1, 2, ...) directive specifies the target string to be used with plural form handling functions ngettext(), dngettext() and dcngettext().

Message strings can contain the following escape sequences:

Table 15-1. Escape Sequences

\nnewline
\ttab
\vvertical tab
\bbackspace
\rcarriage return
\fformfeed
\\backslash
\"double quote
\dddoctal bit pattern
\xHHhexadecimal bit pattern

Comment Handling

Comments are introduced by a #, and continue to the end of the line. The second character (i.e. the character following the #) has special meaning. Regular comments should follow a space character. Other comment types include:

# normal-comments

#. automatic-comments

#: reference...

#, flag

Automatic and reference comments are typically generated by external utilities, and are not specified by the LSB. The msgfmt command shall ignore such comments.

Note: Portable object files may be produced by unspecified tools. Some of the comment types described here may arise from the use of such tools. It is beyond the scope of this specification to describe these tools.

The #, comments require one or more flags separated by the comma (,) character. The following flags can be specified:

fuzzy 

This flag shows that the following msgstr string might not be a correct translation. Only the translator (i.e. the individual undertaking the translation) can judge if the translation requires further modification, or is acceptable as is. Once satisfied with the translation, the translator then 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, unless the --use-fuzzy is specified.

c-format, no-c-format 

The c-format flag indicates that the msgid string is used as format string by printf()-like functions. If the c-format flag is given for a string the msgfmt utility may perform additional tests to check the validity of the translation.

Plurals

The msgid entry with empty string ("") is called the header entry and is 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 4 plural forms. If nplurals is defined, there should be a plural=expression on the same line, separated by a semicolon (;) character. The expression is a C language expression to determine which version of msgstr[n] 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 2 plural forms in the language; msgstr[0] is used if n == 1, otherwise msgstr[1] is used. Another example:

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

indicates that there are 3 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 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 strings's codeset to the output string's codeset will be performed upon the call of gettext(), dgettext(), dcgettext(), ngettext(), dngettext(), and dcngettext(). 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().

Exit Status

The following exit values are returned:

0 

Successful completion.

>0 

An error occurred.

Application Usage

Neither msgfmt nor any gettext() function imposes a limit on the total length of a message. Installing message catalogs under the C locale is pointless, since they are ignored for the sake of efficiency.

Examples

Example 1: Examples of creating message objects from message files.

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

example% cat module1.po

# default domain "messages"

msgid "message one"

msgstr "mensaje número uno"

#

domain "help_domain"

msgid "help two"

msgstr "ayuda número dos"

#

domain "error_domain"

msgid "error three"

msgstr "error número tres"

example% cat module2.po

# default domain "messages"

msgid "message four"

msgstr "mensaje número cuatro"

#

domain "error_domain"

msgid "error five"

msgstr "error número cinco"

#

domain "window_domain"

msgid "window six"

msgstr "ventana número seises"

example% cat module3.po

# default domain "messages"

msgid "message seven"

msgstr "mensaje número siete"

The following command will produce the output files messages, help_domain, and error_domain.

example% msgfmt module1.po

The following command will produce the output files messages.mo, help_domain.mo, error_domain.mo, and window_domain.mo.

example% msgfmt module1.po module2.po

The following example will produce the output file hello.mo.

example% msgfmt -o hello.mo module3.po