GETTEXT(3)

💖 GETTEXT(3) — Library Functions Manual 💖

okay bestie, sit down, hydrate, and let me tell you about gettext, dgettext, and dcgettext — the trio that translates your message. this is a page from the Library Functions Manual and it's genuinely iconic. 🎀

---

✨ NAME ✨

gettext, dgettext, dcgettext — translate message. that's it, that's the whole job. 🌸

---

✨ SYNOPSIS ✨

#include <libintl.h>

char * gettext (const char * msgid);
char * dgettext (const char * domainname, const char * msgid);
char * dcgettext (const char * domainname, const char * msgid,
                  int category);

look at them. three little functions. so much power. 👑

---

✨ DESCRIPTION ✨

so the way that gettext, dgettext and dcgettext work is: they attempt to translate a text string into the user's native language, by looking up the translation in a message catalog. it's giving "your app speaks every language now". 💅

the msgid argument identifies the message to be translated. by convention, it's the English version of the message, with non-ASCII characters replaced by ASCII approximations. why tho? because that choice lets the translators work with message catalogs, called PO files, that contain both the English and the translated versions of each message, and those can be installed using the msgfmt utility. bestie teamwork fr fr. 🫶

a message domain is a set of translatable msgid messages. usually every software package has its own message domain. the domain name is what determines the message catalog where the translation is looked up; it must be a non-empty string. for the gettext function, it's specified through a preceding textdomain call. for the dgettext and dcgettext functions, it's passed as the domainname argument; and if this argument is NULL, the domain name specified through a preceding textdomain call is used instead. sneaky, but valid. 🙈

translation lookup operates in the context of the current locale. for the gettext and dgettext functions, the LC_MESSAGES locale facet is used. it's determined by a preceding call to the setlocale function. setlocale (LC_ALL, "") initializes the LC_MESSAGES locale based on the first nonempty value of the three environment variables LC_ALL, LC_MESSAGES, LANG; see setlocale(3). for the dcgettext function, the locale facet is determined by the category argument, which should be one of the LC_xxx constants defined in the <locale.h> header, excluding LC_ALL. in both cases, the functions also use the LC_CTYPE locale facet in order to convert the translated message from the translator's codeset to the current locale's codeset, unless overridden by a prior call to the bind_textdomain_codeset function. codeset conversion?? she does it all. 💅✨

the message catalog used by the functions is at the pathname dirname/locale/category/domainname.mo. okay let me break that down because it's literally a whole address:

• dirname is the directory specified through bindtextdomain. its default is system and configuration dependent; typically it is prefix/share/locale, where prefix is the installation prefix of the package.
• locale is the name of the current locale facet; the GNU implementation also tries generalizations, such as the language name without the territory name. so if it can't find en_US it's like "okay what about just en". resourceful queen. 👑
• category is LC_MESSAGES for the gettext and dgettext functions, or the argument passed to the dcgettext function.

if the LANGUAGE environment variable is set to a nonempty value, and the locale is not the "C" locale, the value of LANGUAGE is assumed to contain a colon separated list of locale names. the functions will attempt to look up a translation of msgid in each of the locales in turn. this is a GNU extension — special bonus feature, no cap. 🔥

in the "C" locale, or if none of the used catalogs contain a translation for msgid, the gettext, dgettext and dcgettext functions return msgid. so worst case you get your own string back. it's giving "you're on your own bestie" but in a neutral way. 😭

---

✨ RETURN VALUE ✨

if a translation was found in one of the specified catalogs, it is converted to the locale's codeset and returned. 🎉

⚠️ the resulting string is statically allocated and must not be modified or freed. do NOT touch it. do NOT free it. hands off. it's not yours. 💀

otherwise msgid is returned.

---

✨ ERRORS ✨

errno is not modified. no drama, no side quests, nothing. 🙅♀️

---

✨ BUGS ✨

okay so, the return type ought to be const char *, but is char * to avoid warnings in C code predating ANSI C. so it's technically lying to you, but for a good cause. 🌈

also: when an empty string is used for msgid, the functions may return a nonempty string. yes. empty in, maybe not-empty out. that's not a typo, that's just the vibe. 🙈

---

✨ SEE ALSO ✨

• ngettext(3)
• dngettext(3)
• dcngettext(3)
• setlocale(3)
• textdomain(3)
• bindtextdomain(3)
• bind_textdomain_codeset(3)
• msgfmt(1)

---

and that's the whole page, bestie. GNU gettext 1.0, dated November 2024 — go translate something and slay. 💖🦋✨🎀