Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GETTEXT(3)		   Library Functions Manual		    GETTEXT(3)

       gettext,	dgettext, dcgettext - translate	message

       #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);

       The  gettext,  dgettext	and dcgettext functions	attempt	to translate a
       text string into	the user's native language, by looking up the transla-
       tion in a message catalog.

       The  msgid 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 in-
       stalled using the msgfmt	utility.

       A message domain	is a set of translatable msgid messages. Usually,  ev-
       ery  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 gettext function, it is
       specified through a preceding textdomain	call.  For  the	 dgettext  and
       dcgettext  functions,  it is passed as the domainname argument; if this
       argument	is NULL, the domain name specified through a preceding textdo-
       main call is used instead.

       Translation  lookup  operates in	the context of the current locale. For
       the gettext and dgettext	functions, the	LC_MESSAGES  locale  facet  is
       used.  It  is 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_MES-
       SAGES, 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	 code-
       set  to the current locale's codeset, unless overridden by a prior call
       to the bind_textdomain_codeset function.

       The  message  catalog  used  by	the  functions	is  at	the   pathname
       dirname/locale/category/  Here  dirname  is the directory
       specified through bindtextdomain. Its default is	system and  configura-
       tion  dependent;	 typically  it is prefix/share/locale, where prefix is
       the installation	prefix of the package. locale is the name of the  cur-
       rent  locale  facet; the	GNU implementation also	tries generalizations,
       such as the language name  without  the	territory  name.  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  at-
       tempt to	look up	a translation of msgid 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  msgid,  the gettext, dgettext	and dcgettext functions	return

       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 msgid
       is returned.

       errno is	not modified.

       The  return type	ought to be const char *, but is char *	to avoid warn-
       ings in C code predating	ANSI C.

       When an empty string is used for	msgid,	the  functions	may  return  a
       nonempty	string.

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

GNU gettext	   May 2001			    GETTEXT(3)


Want to link to this manual page? Use this URL:

home | help