Section: User Contributed Perl Documentation (3)
Locale::gettext - message handling functions
use Locale::gettext; use POSIX; # Needed for setlocale() setlocale(LC_MESSAGES, ""); # OO interface my $d = Locale::gettext->domain("my_program"); print $d->get("Welcome to my program"), "\n"; # (printed in the local language) # Direct access to C functions textdomain("my_program"); print gettext("Welcome to my program"), "\n"; # (printed in the local language)
The gettext module permits access from perl to the gettext()
family offunctions for retrieving message strings from databases constructedto internationalize software.
- $d = Locale::gettext->domain(DOMAIN)
- $d = Locale::gettext->domain_raw(DOMAIN)
- Creates a new object for retrieving strings in the domain DOMAINand returns it. "domain" requests that strings be returned asPerl strings (possibly with wide characters) if possible while"domain_raw" requests that octet strings directly from functionslike "dgettext()".
- Calls "dgettext()" to return the translated string for the givenMSGID.
- $d->cget(MSGID, CATEGORY)
- Calls "dcgettext()" to return the translated string for the givenMSGID in the given CATEGORY.
- $d->nget(MSGID, MSGID_PLURAL, N)
- Calls "dngettext()" to return the translated string for the givenMSGID or MSGID_PLURAL depending on N.
- $d->ncget(MSGID, MSGID_PLURAL, N, CATEGORY)
- Calls "dngettext()" to return the translated string for the givenMSGID or MSGID_PLURAL depending on N in the givenCATEGORY.
- If NEWDIR is given, calls "bindtextdomain" to set thename of the directory where messages for the domainrepresented by $d are found. Returns the (possibly changed)current directory name.
- For instances created with "Locale::gettext->domain_raw", manuiplatesthe character set of the returned strings.If NEWCODE is given, calls "bind_textdomain_codeset" to set thecharacter encoding in which messages for the domainrepresented by $d are returned. Returns the (possibly changed)current encoding name.
gettext(), dgettext(), and dcgettext() attempt to retrieve a stringmatching their "msgid" parameter within the context of the currentlocale. dcgettext() takes the message's category and the text domainas parameters while dgettext() defaults to the LC_MESSAGES categoryand gettext() defaults to LC_MESSAGES and uses the current text domain.If the string is not found in the database, then "msgid" is returned.
ngettext(), dngettext(), and dcngettext() function similarily butimplement differentiation of messages between singular and plural.See the documentation for the corresponding C functions for details.
textdomain() sets the current text domain and returns the previouslyactive domain.
bindtextdomain(domain, dirname) instructs the retrieval functions to lookfor the databases belonging to domain "domain" in the directory"dirname"
bind_textdomain_codeset(domain, codeset) instructs the retrievalfunctions to translate the returned messages to the character encodinggiven by codeset if the encoding of the message catalog is known.
Not all platforms provide all of the functions. Functions that arenot available in the underlying C library will not be available inPerl either.
Perl programs should use the object interface. In addition to beingable to return native Perl wide character strings,"bind_textdomain_codeset" will be emulated if the C library doesnot provide it.
Kim Vandry <vandryAATTTZoNE.ORG>
- SEE ALSO
This document was created byman2html,using the manual pages.