info > Locale::gettext

📖 NAME

Locale::gettext - message handling functions

🚀 Quick Reference

Use Case	Command	Description
Set locale for translation	setlocale(LC_MESSAGES, "");	Initialise locale for message retrieval
Create domain object	my $d = Locale::gettext->domain("my_program");	Create OO interface for a domain
Get translated string	$d->get("Welcome");	Retrieve translation for a message ID
Get plural translation	$d->nget("one", "%d", $n);	Retrieve singular/plural form
Set current text domain	textdomain("my_program");	Switch to a domain for direct calls
Set message directory	bindtextdomain("my_program", "/path");	Specify where .mo files are stored

📝 SYNOPSIS

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)

📄 DESCRIPTION

The gettext module permits access from perl to the gettext() family of functions for retrieving message strings from databases constructed to internationalize software.

📦 Domain Object Methods

• $d = Locale::gettext->domain(DOMAIN) — Creates a new object for retrieving strings in the domain DOMAIN and returns it. "domain" requests that strings be returned as Perl strings (possibly with wide characters) if possible.
• $d = Locale::gettext->domain_raw(DOMAIN) — Creates a new object that requests octet strings directly from functions like "dgettext()".
• $d->get(MSGID) — Calls "dgettext()" to return the translated string for the given MSGID.
• $d->cget(MSGID, CATEGORY) — Calls "dcgettext()" to return the translated string for the given MSGID in the given CATEGORY.
• $d->nget(MSGID, MSGID_PLURAL, N) — Calls "dngettext()" to return the translated string for the given MSGID or MSGID_PLURAL depending on N.
• $d->ncget(MSGID, MSGID_PLURAL, N, CATEGORY) — Calls "dngettext()" to return the translated string for the given MSGID or MSGID_PLURAL depending on N in the given CATEGORY.
• $d->dir([NEWDIR]) — If NEWDIR is given, calls "bindtextdomain" to set the name of the directory where messages for the domain represented by $d are found. Returns the (possibly changed) current directory name.
• $d->codeset([NEWCODE]) — For instances created with "Locale::gettext->domain_raw", manipulates the character set of the returned strings. If NEWCODE is given, calls "bind_textdomain_codeset" to set the character encoding. Returns the (possibly changed) current encoding name.

🔧 Direct Function Calls

• gettext(), dgettext(), and dcgettext() — These functions attempt to retrieve a string matching their "msgid" parameter within the context of the current locale. dcgettext() takes the message's category and the text domain as parameters while dgettext() defaults to the LC_MESSAGES category and 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() — These function similarly but implement 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 previously active domain.
• bindtextdomain(domain, dirname) — Instructs the retrieval functions to look for the databases belonging to domain "domain" in the directory "dirname".
• bind_textdomain_codeset(domain, codeset) — Instructs the retrieval functions to translate the returned messages to the character encoding given by codeset if the encoding of the message catalog is known.

📌 NOTES

Not all platforms provide all of the functions. Functions that are not available in the underlying C library will not be available in Perl either.

Perl programs should use the object interface. In addition to being able to return native Perl wide character strings, "bind_textdomain_codeset" will be emulated if the C library does not provide it.

📚 VERSION

1.07.

🔗 SEE ALSO

gettext(3i), gettext(1), msgfmt(1)

👤 AUTHOR

Kim Vandry <vandry AT TZoNE.ORG>

perl v5.34.0 2022-02-06 gettext(3pm)