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 textdomaindir 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 textdomain, if present
The -d textdomain 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() function with a base 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 universal-character-name 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 12.2 Utility Syntax Guidelines .
The following options shall be supported:
- -d textdomain
Retrieve the translated message from the domain textdomain, if textdomain is not specified as an operand.- -e
- Process C-language escape sequences in msgid and msgid_plural operands.
- -E
- Do not process C-language escape sequences in msgid and msgid_plural operands.
The gettext utility shall also support the following options:
- -n
- Modify the behavior of the -s option such that a <newline> is not appended to the output.
- -s
- 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 ).
The following environment variables shall affect the execution of gettext and ngettext:
- LANG
- Provide a default value for the internationalization variables that are unset or null. (See XBD 8.2 Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
- LANGUAGE
- 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.
- LC_ALL
- If set to a non-empty string value, override the values of all the other internationalization variables.
- LC_MESSAGES
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.- NLSPATH
- [XSI] Determine the location of messages objects and message catalogs.
- TEXTDOMAIN
Specify the text domain name. (See XBD 3.386 Text Domain .)- TEXTDOMAINDIR
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:
- 0
- Successful completion.
- >0
- 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 utility. See the EXTENDED DESCRIPTION section of the msgfmt 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() for details on how this search is performed.
The command
ngettext -d mail recipient recipients 0will write "no recipients".
The command
ngettext -d mail recipient recipients 1will write "1 recipient".
The command
ngettext -d mail recipient recipients 5will write "2 to 10 recipients".
The command
ngettext -d mail recipient recipients 11will write "more than 10 recipients".
The command
ngettext -d mail Call Calls 1will write "Call". Note that "Call" is not in the messages object.
The command
ngettext -d mail Call Calls 0will write "Calls".
The command
ngettext -d mail Call Calls 10will write "Calls".
The command
ngettext -ed mail "%d attachment\n" "%d attachments\n" 1will 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.
The command
printf "$(ngettext -ed mail "%d attachment\n" "%d attachments\n" 1)" 10will 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" 0will 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 5. File Format Notation .
Unlike other standard utilities, the behavior of gettext and ngettext is not undefined when NLSPATH overrides the system default path; see XBD 8.2 Internationalization Variables . 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.
XBD 7. Locale , 8. Environment Variables , 12.2 Utility Syntax Guidelines
First released in Issue 8.
return to top of page