.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Locale::gettext_dumb 3pm"
.TH Locale::gettext_dumb 3pm "2022-12-22" "perl v5.36.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_dumb \- Locale unaware Implementation of Uniforum Message Translation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Locale::gettext_dumb qw(:locale_h :libintl_h);
\&
\& # Normally, you will not want to include this module directly but this way:
\& use Locale::Messages;
\&
\& my $selected = Locale::Messages\->select_package (\*(Aqgettext_dumb\*(Aq);
\&
\& gettext $msgid;
\& dgettext $domainname, $msgid;
\& dcgettext $domainname, $msgid, LC_MESSAGES;
\& ngettext $msgid, $msgid_plural, $count;
\& dngettext $domainname, $msgid, $msgid_plural, $count;
\& dcngettext $domainname, $msgid, $msgid_plural, $count, LC_MESSAGES;
\& pgettext $msgctxt, $msgid;
\& dpgettext $domainname, $msgctxt, $msgid;
\& dcpgettext $domainname, $msgctxt, $msgid, LC_MESSAGES;
\& npgettext $msgctxt, $msgid, $msgid_plural, $count;
\& dnpgettext $domainname, $msgctxt, $msgid, $msgid_plural, $count;
\& dcnpgettext $domainname, $msgctxt, $msgid, $msgid_plural, $count, LC_MESSAGES;
\& textdomain $domainname;
\& bindtextdomain $domainname, $directory;
\& bind_textdomain_codeset $domainname, $encoding;
\& my $category = LC_CTYPE;
\& my $category = LC_NUMERIC;
\& my $category = LC_TIME;
\& my $category = LC_COLLATE;
\& my $category = LC_MONETARY;
\& my $category = LC_MESSAGES;
\& my $category = LC_ALL;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1IMPORTANT\s0!\fR This module is experimental. It may not work as described!
.PP
The module \fBLocale::gettext_dumb\fR does exactly the same as
\&\fBLocale::gettext_xs\fR\|(3pm) or \fBLocale::gettext_pp\fR\|(3pm).
.PP
While both other modules use \fBPOSIX::setlocale()\fR to determine the currently
selected locale, this backend only checks the environment variables
\&\s-1LANGUAGE, LANG, LC_ALL, LC_MESSAGES\s0 (in that order), when it tries to locate
a message catalog (a .mo file).
.PP
This class was introduced in libintl-perl 1.22.
.SH "USAGE"
.IX Header "USAGE"
This module should not be used for desktop software or scripts run locally.
Why? If you use a message catalog for example in Danish in \s-1UTF\-8\s0 (da_DA.UTF8)
but the system locale is set to Russian with \s-1KOI8\-R\s0 (ru_RU.KOI8\-R) you
may produce invalid output, either invalid multi-byte sequences or invalid
text, depending on how you look at it.
.PP
That will happen, when you mix output from \fBLocale::gettext_pp\fR with
locale-dependent output from the operating system like the contents of
the variable \*(L"$!\*(R", date and time formatting functions (\fBlocaltime()\fR,
\&\fBgmtime()\fR, \fBPOSIX::strftime()\fR etc.), number formatting with \fBprintf()\fR and
friends, and so on.
.PP
A typical usage scenario looks like this:
.PP
You have a server application (for example a web application) that is supposed
to display a fixed set of messages in many languages. If you want to do this
with \fBLocale::gettext_xs\fR\|(3pm) or \fBLocale::gettext_pp\fR\|(3pm), you have to install
the locale data for all of those languages. Otherwise, translating the
messages will not work.
.PP
With \fBLocale::gettext_dumb\fR\|(3pm) you can relax these requirements, and display
messages for all languages that you have mo files for.
.PP
On the other hand, you will soon reach limits with this approach. Almost
any application requires more than bare translation of messages for
localisation. You want to formatted dates and times, you want to display
numbers in the correct formatting for the selected languages, and you may
want to display system error messages (\*(L"$!\*(R").
.PP
In practice, \fBLocale::gettext_dumb\fR\|(3pm) is still useful in these scenarios.
Your users will have to live with the fact that the presented output is
in different languages resp. for different locales, when \*(L"their\*(R" locale
is not installed on your system.
.PP
More dangerous is mixing output in different character sets but that can
be easily avoided. Simply make sure that \fBLocale::gettext_dump\fR uses
\&\s-1UTF\-8\s0 (for example by setting the environment variable \s-1OUTPUT_CHARSET\s0 or
by calling \fBbind_textdomain_codeset()\fR) and make sure that the system locale
also uses \s-1UTF\-8,\s0 for example \*(L"en_US.UTF8\*(R". If that fails, switch to a
locale that uses a subset of \s-1UTF\-8.\s0 In practice that will be US-ASCII, the
character set used by the default locale \*(L"C\*(R" resp. \*(L"\s-1POSIX\*(R".\s0
.PP
Your application will then to a certain extent mix output for different
localisations resp. languages. But this is completely under your control.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
See above! Normally you should not use this module! However, let us assume
you have read the warnings. In a web application you would do something
like this:
.PP
.Vb 5
\& use Locale::TextDomain qw (com.example.yourapp);
\& use Locale::Messages qw (nl_putenv LC_ALL bindtextdomain
\& bind_textdomain_codeset);
\& use Locale::Util qw (web_set_locale);
\& use POSIX qw (setlocale);
\&
\& # First try to switch to the locale requested by the user. If you
\& # know it you can try to pass it to setlocale like this:
\& #
\& # my $hardcoded_locale = \*(Aqfr_FR.UTF\-8\*(Aq;
\& # my $success = POSIX::setlocale (LC_ALL, $hardcoded_locale);
\& #
\& # However, we try to let libintl\-perl do a better job for us:
\& my $success = web_set_locale $ENV{HTTP_ACCEPT_LANGUAGE},
\& $ENV{HTTP_ACCEPT_CHARSET};
\& # Note: If your application forces the use of UTF\-8 for its output
\& # you should pass \*(AqUTF\-8\*(Aq as the second argument to web_set_locale
\& # instead of $ENV{HTTP_ACCEPT_CHARSET}.
\&
\& if (!$success) {
\& # Did not work. Switch to the dumb interface of
\& # Locale::Messages.
\& Locale::Messages\->select_package (\*(Aqgettext_dumb\*(Aq);
\&
\& # And try to switch to a default locale:
\& if (!setlocale (LC_ALL, \*(Aqen_US.UTF\-8\*(Aq)) {
\& # Still no luck. Enforce at least US\-ASCII:
\& setlocale (LC_ALL, \*(AqC\*(Aq);
\& }
\& bind_textdomain_codeset \*(Aqcom.example.yourapp\*(Aq, \*(Aqutf\-8\*(Aq;
\& }
.Ve
.PP
If your application forces the usage of \s-1UTF\-8\s0 you should ignore the environment
variable
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) 2002\-2017 Guido Flohr
(), all rights reserved. See the source
code for details!code for details!
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBLocale::TextDomain\fR\|(3pm), \fBLocale::Messages\fR\|(3pm), \fBEncode\fR\|(3pm),
\&\fBperllocale\fR\|(3pm), \s-1\fBPOSIX\s0\fR\|(3pm), \fBperl\fR\|(1), \fBgettext\fR\|(1), \fBgettext\fR\|(3)