GETTEXT(3) Library Functions Manual GETTEXT(3) NNAAMMEE gettext, dgettext, dcgettext - translate message SSYYNNOOPPSSIISS ##iinncclluuddee <> cchhaarr ** ggeetttteexxtt ((ccoonnsstt cchhaarr ** _m_s_g_i_d));; cchhaarr ** ddggeetttteexxtt ((ccoonnsstt cchhaarr ** _d_o_m_a_i_n_n_a_m_e,, ccoonnsstt cchhaarr ** _m_s_g_i_d));; cchhaarr ** ddccggeetttteexxtt ((ccoonnsstt cchhaarr ** _d_o_m_a_i_n_n_a_m_e,, ccoonnsstt cchhaarr ** _m_s_g_i_d,, iinntt _c_a_t_e_g_o_r_y));; DDEESSCCRRIIPPTTIIOONN The ggeetttteexxtt, ddggeetttteexxtt and ddccggeetttteexxtt functions attempt to translate a text string into the user's native language, by looking up the transla- tion in a message catalog. The _m_s_g_i_d argument identifies the message to be translated. By conven- tion, it is the English version of the message, with non-ASCII charac- ters replaced by ASCII approximations. This choice allows the transla- tors to work with message catalogs, called PO files, that contain both the English and the translated versions of each message, and can be installed using the mmssggffmmtt utility. A message domain is a set of translatable _m_s_g_i_d messages. Usually, every software package has its own message domain. The domain name is used to determine the message catalog where the translation is looked up; it must be a non-empty string. For the ggeetttteexxtt function, it is specified through a preceding tteexxttddoommaaiinn call. For the ddggeetttteexxtt and ddccggeetttteexxtt functions, it is passed as the _d_o_m_a_i_n_n_a_m_e argument; if this argument is NULL, the domain name specified through a preceding tteexxttddoo-- mmaaiinn call is used instead. Translation lookup operates in the context of the current locale. For the ggeetttteexxtt and ddggeetttteexxtt functions, the LLCC__MMEESSSSAAGGEESS locale facet is used. It is determined by a preceding call to the sseettllooccaallee function. sseettllooccaallee((LLCC__AALLLL,,"""")) initializes the LLCC__MMEESSSSAAGGEESS locale based on the first nonempty value of the three environment variables LLCC__AALLLL, LLCC__MMEESS-- SSAAGGEESS, LLAANNGG; see sseettllooccaallee(3). For the ddccggeetttteexxtt function, the locale facet is determined by the _c_a_t_e_g_o_r_y argument, which should be one of the LLCC__xxxxxx constants defined in the header, excluding LLCC__AALLLL. In both cases, the functions also use the LLCC__CCTTYYPPEE locale facet in order to convert the translated message from the translator's code- set to the current locale's codeset, unless overridden by a prior call to the bbiinndd__tteexxttddoommaaiinn__ccooddeesseett function. The message catalog used by the functions is at the pathname _d_i_r_n_a_m_e/_l_o_c_a_l_e/_c_a_t_e_g_o_r_y/_d_o_m_a_i_n_n_a_m_e.mo. Here _d_i_r_n_a_m_e is the directory specified through bbiinnddtteexxttddoommaaiinn. Its default is system and configura- tion dependent; typically it is _p_r_e_f_i_x/share/locale, where _p_r_e_f_i_x is the installation prefix of the package. _l_o_c_a_l_e is the name of the cur- rent locale facet; the GNU implementation also tries generalizations, such as the language name without the territory name. _c_a_t_e_g_o_r_y is LLCC__MMEESSSSAAGGEESS for the ggeetttteexxtt and ddggeetttteexxtt functions, or the argument passed to the ddccggeetttteexxtt function. If the LLAANNGGUUAAGGEE environment variable is set to a nonempty value, and the locale is not the "C" locale, the value of LLAANNGGUUAAGGEE is assumed to contain a colon separated list of locale names. The functions will attempt to look up a translation of _m_s_g_i_d in each of the locales in turn. This is a GNU extension. In the "C" locale, or if none of the used catalogs contain a transla- tion for _m_s_g_i_d, the ggeetttteexxtt, ddggeetttteexxtt and ddccggeetttteexxtt functions return _m_s_g_i_d. RREETTUURRNN VVAALLUUEE If a translation was found in one of the specified catalogs, it is con- verted to the locale's codeset and returned. The resulting string is statically allocated and must not be modified or freed. Otherwise _m_s_g_i_d is returned. EERRRROORRSS eerrrrnnoo is not modified. BBUUGGSS The return type ought to be ccoonnsstt cchhaarr **, but is cchhaarr ** to avoid warn- ings in C code predating ANSI C. When an empty string is used for _m_s_g_i_d, the functions may return a nonempty string. SSEEEE AALLSSOO nnggeetttteexxtt(3), ddnnggeetttteexxtt(3), ddccnnggeetttteexxtt(3), sseettllooccaallee(3), tteexxttddoommaaiinn(3), bbiinnddtteexxttddoommaaiinn(3), bbiinndd__tteexxttddoommaaiinn__ccooddeesseett(3), mmssggffmmtt(1) GNU gettext 0.20.1 May 2001 GETTEXT(3)