GETTEXT(1) General Commands Manual GETTEXT(1)

gettext ngettext — retrieve text string from messages object

gettext [-e | -E] [-d textdomain] [textdomain] msgid

gettext [-e | -E] [-n] -s [-d textdomain] msgid... ngettext [-e | -E] [-d textdomain] [textdomain] msgid msgid_plural n

The gettext and ngettext utilities shall write to standard output the message string(s) that would result from the following calls to functions defined in the System Interfaces volume of POSIX.1-2024:

if (textdomainname == NULL || textdomainname[0] == '\0')
    message_string = msgid;
else {
    setlocale(LC_ALL, "");
    if (textdomaindir != NULL)
        bindtextdomain(textdomainname, textdomaindir);
    if (msgid_plural == NULL)
        message_string = dgettext(textdomainname, msgid);
    else
        message_string = dngettext(textdomainname, msgid, msgid_plural, n);
}

where:

  • The variable is a string containing the value of the TEXTDOMAINDIR environment variable, if set and not empty, or is NULL otherwise.
  • The textdomainname variable is a string containing the text domain name obtained from, in decreasing order of precedence:
    • The optional operand if present
    • The -d option, if specified
    • The TEXTDOMAIN environment variable, if set and not empty

    If the text domain name cannot be obtained from these sources, the textdomainname variable is NULL.

  • If the -s option of gettext is not specified and for the ngettext utility, the msgid variable is a string containing:
    • The value of the msgid operand, if the -E option is specified
    • The value of the msgid operand with C-language escape sequences processed (see below), if the -e option is specified
    • The value of the msgid operand with C-language escape sequences optionally processed (see below), otherwise
  • If the -s option of gettext is specified, the msgid variable is a string containing:
    • The value of each msgid operand in turn, if the -E option is specified or neither the -e nor the -E option is specified
    • The value of each msgid operand in turn with C-language escape sequences processed (see below), if the -e option is specified
  • For the gettext utility, the msgid_plural variable is NULL. For the ngettext utility, the msgid_plural variable is a string containing:
    • The value of the msgid_plural operand, if the -E option is specified
    • The value of the msgid_plural operand with C-language escape sequences processed (see below), if the -e option is specified
    • The value of the msgid_plural operand with C-language escape sequences optionally processed (see below), otherwise
  • For the gettext utility, the n variable is 1 (one). For the ngettext utility the n variable is the n operand, parsed as an integer as if by using the strtoul(3) function with a argument of 10.

When C-language escape sequences are processed, they shall be processed as specified for character string literals in the ISO C standard, except that escape sequences need not be supported. Implementations may also support a <backslash> ‘c’ escape sequence; if supported, the ‘\c’ and all characters following it shall be removed and, if the -s option is specified, the behavior shall be as if the -n option is also specified.

For the ngettext utility, and for the gettext utility if the -s option is not specified, the resulting message string shall be written to standard output. If the -s option of gettext is specified, the resulting message string for each msgid shall be written to standard output with consecutive message strings separated by a single <space> character and, if the -n option is not specified, a <newline> shall be written after the last message string. If the -s and -n options are specified, the trailing <newline> shall be omitted.

Under conditions where the textdomainname variable in the above code would be NULL, these utilities may write a diagnostic message to standard error and exit with non-zero status.

These utilities shall conform to XBD V1_chap12(7) .

The following options shall be supported:


Retrieve the translated message from the domain textdomain , if textdomain is not specified as an operand.
Process C-language escape sequences in msgid and msgid_plural operands.
Do not process C-language escape sequences in msgid and msgid_plural operands.

The gettext utility shall also support the following options:

Modify the behavior of the -s option such that a <newline> is not appended to the output.
Separate the message strings obtained from each msgid operand with <space> characters in the output, and (if -n is not also specified) append a <newline> to the output.

If neither of the mutually exclusive -e and -E options is specified, it is unspecified which is the default, except that if the -s option of gettext is specified then -E shall be the default.

The following operands shall be supported:

textdomain
A text domain name used to retrieve the translated message. This shall override the specification by the -d option, if present.
msgid
A key to retrieve the translated message.
msgid_plural
A default plural if no corresponding plural message can be found.
n
A non-negative decimal integer to be used as the n argument to dngettext () (see the DESCRIPTION).

Not used.

The input files are messages object files (see msgfmt(1)).

The following environment variables shall affect the execution of gettext and ngettext:

Provide a default value for the internationalization variables that are unset or null. (See XBD for the precedence of internationalization variables used to determine the values of locale categories.)
Determine the location of messages objects [ XSI] if NLSPATH is not set or the evaluation of NLSPATH did not lead to a suitable messages object being found.
If set to a non-empty string value, override the values of all the other internationalization variables.

Determine the locale name used to locate messages objects, and the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
[ XSI] Determine the location of messages objects and message catalogs.

Specify the text domain name. (See XBD .)

Specify the pathname to the messages object hierarchy. [ XSI] NLSPATH shall have precedence over TEXTDOMAINDIR .

Default.

See DESCRIPTION.

The standard error shall be used only for diagnostic messages.

None.

None.

The following exit values shall be returned:

Successful completion.
An error occurred.

Default.

Since it is unspecified which of the -e or -E options is the default, except when the -s option of gettext is specified, portable applications need to ensure that -e, -E, or (for gettext) -s is specified whenever a msgid or msgid_plural operand contains, or might contain, a <backslash> character.

Note that, unless the -s option of gettext is specified without -n, the message(s) written to standard output are not followed by a <newline>. (Therefore the output only ends with a <newline> if the last message ends with one.)

Both msgid and msgid_plural should be properly quoted for the shell.

The following examples assume that the following portable messages object source file (dot-po file) has been compiled to a valid file mail.mo by the msgfmt(1) utility. See the EXTENDED DESCRIPTION section of the msgfmt(1) utility for a description of the dot-po file format.

msgid ""
msgstr ""
"Content-Type: text/plain; charset=utf-8\n"
"Plural-Forms: nplurals=4; plural=n==1?0: (n>1&&n<=10)?1: (n==0)?2:3;\n"


msgid "recipient"
msgid_plural "recipients"
msgstr[0] "1 recipient"
msgstr[1] "2 to 10 recipients"
msgstr[2] "no recipients"
msgstr[3] "more than 10 recipients"


msgid "%d attachment\n"
msgid_plural "%d attachments\n"
msgstr[0] "1 (%d) attachment\n"
msgstr[1] "2 to 10 (%d) attachments\n"
msgstr[2] "no (%d) attachments\n"
msgstr[3] "more than 10 (%d) attachments\n"

They also assume that mail.mo is installed in the directory that gettext and ngettext search for the current locale. See the OPTIONS and ENVIRONMENT VARIABLES sections above and the description of gettext(3) for details on how this search is performed.

The command

ngettext -d mail recipient recipients 0

will write "no recipients".

The command

ngettext -d mail recipient recipients 1

will write "1 recipient".

The command

ngettext -d mail recipient recipients 5

will write "2 to 10 recipients".

The command

ngettext -d mail recipient recipients 11

will write "more than 10 recipients".

The command

ngettext -d mail Call Calls 1

will write "Call". Note that "Call" is not in the messages object.

The command

ngettext -d mail Call Calls 0

will write "Calls".

The command

ngettext -d mail Call Calls 10

will write "Calls".

The command

ngettext -ed mail "%d attachment\n" "%d attachments\n" 1

will write the same as

printf "1 (%%d) attachment\n"

(i.e. "1 (%d) attachment" followed by a <newline> character). The output of ngettext can be used as a format string for printf(1).

The command

printf "$(ngettext -ed mail "%d attachment\n" "%d attachments\n" 1)" 10

will write the same as

printf "1 (%d) attachment\n" 10

(i.e. "1 (10) attachment" followed by a <newline> character).

The command

ngettext -e -d mail "\tsubject\n" "\tsubjects\n" 0

will write the same as

printf "\tsubjects\n"

(i.e. a <tab> character, followed by "subjects" followed by a <newline> character). Note that "\tsubject\n" is not in the messages object.

The command

printf "%s\n" "$(ngettext -E -d mail "subject" "subjects" 0)"

will write the same as

printf "subjects\n"

(i.e. "subjects" followed by a <newline> character). Note that "subject" is not in the messages object.

The command

gettext -s -d mail "recipient"

will write "1 recipient" followed by a <newline> character.

The command

gettext -s -n -d mail "recipient"

will write "1 recipient" without a <newline> character.

Historical implementations did not support the ‘\a’ C-language escape sequence. This standard requires it to be supported for consistency with other utilities that support the table in XBD V1_chap05(7).

Unlike other standard utilities, the behavior of gettext and ngettext is not undefined when NLSPATH overrides the system default path; see XBD V1_chap08(7). This is so that applications can use these utilities to obtain message strings from messages objects in other locations. However, it also means that they need to be implemented in such a way that they do not do anything that would result in undefined behavior when they need to write a diagnostic message. In particular, they should not use a string obtained from a message catalog or a messages object as a format string (or should only do so after checking that the string contains the correct conversions).

None.

msgfmt(1), printf(1)

XBD V1_chap07(7), V1_chap08(7), V1_chap12(7)

XSH gettext(3), iconv(3), setlocale(3)

First released in Issue 8.

June 14, 2024 posix.fail