.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "gettext 3pm" .TH gettext 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Locale::gettext \- message handling functions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& 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"), "\en"; \& # (printed in the local language) \& \& # Direct access to C functions \& textdomain("my_program"); \& \& print gettext("Welcome to my program"), "\en"; \& # (printed in the local language) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The gettext module permits access from perl to the \fBgettext()\fR family of functions for retrieving message strings from databases constructed to internationalize software. .ie n .IP "$d = Locale::gettext\->domain(\s-1DOMAIN\s0)" 2 .el .IP "\f(CW$d\fR = Locale::gettext\->domain(\s-1DOMAIN\s0)" 2 .IX Item "$d = Locale::gettext->domain(DOMAIN)" .PD 0 .ie n .IP "$d = Locale::gettext\->domain_raw(\s-1DOMAIN\s0)" 2 .el .IP "\f(CW$d\fR = Locale::gettext\->domain_raw(\s-1DOMAIN\s0)" 2 .IX Item "$d = Locale::gettext->domain_raw(DOMAIN)" .PD Creates a new object for retrieving strings in the domain \fB\s-1DOMAIN\s0\fR and returns it. \f(CW\*(C`domain\*(C'\fR requests that strings be returned as Perl strings (possibly with wide characters) if possible while \&\f(CW\*(C`domain_raw\*(C'\fR requests that octet strings directly from functions like \f(CW\*(C`dgettext()\*(C'\fR. .ie n .IP "$d\->get(\s-1MSGID\s0)" 2 .el .IP "\f(CW$d\fR\->get(\s-1MSGID\s0)" 2 .IX Item "$d->get(MSGID)" Calls \f(CW\*(C`dgettext()\*(C'\fR to return the translated string for the given \&\fB\s-1MSGID\s0\fR. .ie n .IP "$d\->cget(\s-1MSGID, CATEGORY\s0)" 2 .el .IP "\f(CW$d\fR\->cget(\s-1MSGID, CATEGORY\s0)" 2 .IX Item "$d->cget(MSGID, CATEGORY)" Calls \f(CW\*(C`dcgettext()\*(C'\fR to return the translated string for the given \&\fB\s-1MSGID\s0\fR in the given \fB\s-1CATEGORY\s0\fR. .ie n .IP "$d\->nget(\s-1MSGID, MSGID_PLURAL, N\s0)" 2 .el .IP "\f(CW$d\fR\->nget(\s-1MSGID, MSGID_PLURAL, N\s0)" 2 .IX Item "$d->nget(MSGID, MSGID_PLURAL, N)" Calls \f(CW\*(C`dngettext()\*(C'\fR to return the translated string for the given \&\fB\s-1MSGID\s0\fR or \fB\s-1MSGID_PLURAL\s0\fR depending on \fBN\fR. .ie n .IP "$d\->ncget(\s-1MSGID, MSGID_PLURAL, N, CATEGORY\s0)" 2 .el .IP "\f(CW$d\fR\->ncget(\s-1MSGID, MSGID_PLURAL, N, CATEGORY\s0)" 2 .IX Item "$d->ncget(MSGID, MSGID_PLURAL, N, CATEGORY)" Calls \f(CW\*(C`dngettext()\*(C'\fR to return the translated string for the given \&\fB\s-1MSGID\s0\fR or \fB\s-1MSGID_PLURAL\s0\fR depending on \fBN\fR in the given \&\fB\s-1CATEGORY\s0\fR. .ie n .IP "$d\->dir([\s-1NEWDIR\s0])" 2 .el .IP "\f(CW$d\fR\->dir([\s-1NEWDIR\s0])" 2 .IX Item "$d->dir([NEWDIR])" If \fB\s-1NEWDIR\s0\fR is given, calls \f(CW\*(C`bindtextdomain\*(C'\fR to set the name of the directory where messages for the domain represented by \f(CW$d\fR are found. Returns the (possibly changed) current directory name. .ie n .IP "$d\->codeset([\s-1NEWCODE\s0])" 2 .el .IP "\f(CW$d\fR\->codeset([\s-1NEWCODE\s0])" 2 .IX Item "$d->codeset([NEWCODE])" For instances created with \f(CW\*(C`Locale::gettext\->domain_raw\*(C'\fR, manuiplates the character set of the returned strings. If \fB\s-1NEWCODE\s0\fR is given, calls \f(CW\*(C`bind_textdomain_codeset\*(C'\fR to set the character encoding in which messages for the domain represented by \f(CW$d\fR are returned. Returns the (possibly changed) current encoding name. .PP \&\fBgettext()\fR, \fBdgettext()\fR, and \fBdcgettext()\fR attempt to retrieve a string matching their \f(CW\*(C`msgid\*(C'\fR parameter within the context of the current locale. \fBdcgettext()\fR takes the message's category and the text domain as parameters while \fBdgettext()\fR defaults to the \s-1LC_MESSAGES\s0 category and \fBgettext()\fR defaults to \s-1LC_MESSAGES\s0 and uses the current text domain. If the string is not found in the database, then \f(CW\*(C`msgid\*(C'\fR is returned. .PP \&\fBngettext()\fR, \fBdngettext()\fR, and \fBdcngettext()\fR function similarily but implement differentiation of messages between singular and plural. See the documentation for the corresponding C functions for details. .PP \&\fBtextdomain()\fR sets the current text domain and returns the previously active domain. .PP \&\fIbindtextdomain(domain, dirname)\fR instructs the retrieval functions to look for the databases belonging to domain \f(CW\*(C`domain\*(C'\fR in the directory \&\f(CW\*(C`dirname\*(C'\fR .PP \&\fIbind_textdomain_codeset(domain, codeset)\fR instructs the retrieval functions to translate the returned messages to the character encoding given by \fBcodeset\fR if the encoding of the message catalog is known. .SH "NOTES" .IX Header "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. .PP Perl programs should use the object interface. In addition to being able to return native Perl wide character strings, \&\f(CW\*(C`bind_textdomain_codeset\*(C'\fR will be emulated if the C library does not provide it. .SH "VERSION" .IX Header "VERSION" 1.07. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBgettext\fR\|(3i), \fBgettext\fR\|(1), \fBmsgfmt\fR\|(1) .SH "AUTHOR" .IX Header "AUTHOR" Kim Vandry