gettext(3) User Contributed Perl Documentation gettext(3)

# [NAME](#NAME)

Locale::gettext - message handling functions

# [SYNOPSIS](#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](#DESCRIPTION)

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

$d = Locale::gettext->domain(DOMAIN)

$d = Locale::gettext->domain\_raw(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 while "domain\_raw" requests that 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", manuiplates the character set of the returned strings. If **NEWCODE** is given, calls "bind\_textdomain\_codeset" to set the character encoding in which messages for the domain represented by $d are returned. Returns the (possibly changed) current encoding name.

**gettext()**, **dgettext()**, and **dcgettext()** 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()** function similarily 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](#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](#VERSION)

1.07.

# [SEE ALSO](#SEE_ALSO)

[**gettext**(3i)](/man/os/perl-locale-gettext/gettext.3i), [**gettext**(1)](/man/os/perl-locale-gettext/gettext.1), [**msgfmt**(1)](/man/os/perl-locale-gettext/msgfmt.1)

# [AUTHOR](#AUTHOR)

Kim Vandry <vandry@TZoNE.ORG>

# [LICENSE](#LICENSE)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.0 or, at your option, any later version of Perl 5 you may have available.

2026-08-30 perl v5.44.0

---

Document: Locale::gettext(3pm) from perl-locale-gettext 1.07-r4 (Chainguard OS)
Source: https://github.com/vandry/Perl-Locale-gettext