1Locale::gettext_dumb(3)User Contributed Perl DocumentatioLnocale::gettext_dumb(3)
2
3
4

NAME

6       Locale::gettext_dumb - Locale unaware Implementation of Uniforum
7       Message Translation
8

SYNOPSIS

10        use Locale::gettext_dumb qw(:locale_h :libintl_h);
11
12        # Normally, you will not want to include this module directly but this way:
13        use Locale::Messages;
14
15        my $selected = Locale::Messages->select_package ('gettext_dumb');
16
17        gettext $msgid;
18        dgettext $domainname, $msgid;
19        dcgettext $domainname, $msgid, LC_MESSAGES;
20        ngettext $msgid, $msgid_plural, $count;
21        dngettext $domainname, $msgid, $msgid_plural, $count;
22        dcngettext $domainname, $msgid, $msgid_plural, $count, LC_MESSAGES;
23        pgettext $msgctxt, $msgid;
24        dpgettext $domainname, $msgctxt, $msgid;
25        dcpgettext $domainname, $msgctxt, $msgid, LC_MESSAGES;
26        npgettext $msgctxt, $msgid, $msgid_plural, $count;
27        dnpgettext $domainname, $msgctxt, $msgid, $msgid_plural, $count;
28        dcnpgettext $domainname, $msgctxt, $msgid, $msgid_plural, $count, LC_MESSAGES;
29        textdomain $domainname;
30        bindtextdomain $domainname, $directory;
31        bind_textdomain_codeset $domainname, $encoding;
32        my $category = LC_CTYPE;
33        my $category = LC_NUMERIC;
34        my $category = LC_TIME;
35        my $category = LC_COLLATE;
36        my $category = LC_MONETARY;
37        my $category = LC_MESSAGES;
38        my $category = LC_ALL;
39

DESCRIPTION

41       IMPORTANT! This module is experimental.  It may not work as described!
42
43       The module Locale::gettext_dumb does exactly the same as
44       Locale::gettext_xs(3pm) or Locale::gettext_pp(3pm).
45
46       While both other modules use POSIX::setlocale() to determine the
47       currently selected locale, this backend only checks the environment
48       variables LANGUAGE, LANG, LC_ALL, LC_MESSAGES (in that order), when it
49       tries to locate a message catalog (a .mo file).
50
51       This class was introduced in libintl-perl 1.22.
52

USAGE

54       This module should not be used for desktop software or scripts run
55       locally.  Why? If you use a message catalog for example in Danish in
56       UTF-8 (da_DA.UTF8) but the  system locale is set to Russian with KOI8-R
57       (ru_RU.KOI8-R) you may produce invalid output, either invalid multi-
58       byte sequences or invalid text, depending on how you look at it.
59
60       That will happen, when you mix output from Locale::gettext_pp with
61       locale-dependent output from the operating system like the contents of
62       the variable "$!", date and time formatting functions (localtime(),
63       gmtime(), POSIX::strftime() etc.), number formatting with printf() and
64       friends, and so on.
65
66       A typical usage scenario looks like this:
67
68       You have a server application (for example a web application) that is
69       supposed to display a fixed set of messages in many languages.  If you
70       want to do this with Locale::gettext_xs(3pm) or
71       Locale::gettext_pp(3pm), you have to install the locale data for all of
72       those languages.  Otherwise, translating the messages will not work.
73
74       With Locale::gettext_dumb(3pm) you can relax these requirements, and
75       display messages for all languages that you have mo files for.
76
77       On the other hand, you will soon reach limits with this approach.
78       Almost any application requires more than bare translation of messages
79       for localisation.  You want to formatted dates and times, you want to
80       display numbers in the correct formatting for the selected languages,
81       and you may want to display system error messages ("$!").
82
83       In practice, Locale::gettext_dumb(3pm) is still useful in these
84       scenarios.  Your users will have to live with the fact that the
85       presented output is in different languages resp. for different locales,
86       when "their" locale is not installed on your system.
87
88       More dangerous is mixing output in different character sets but that
89       can be easily avoided.  Simply make sure that Locale::gettext_dump uses
90       UTF-8 (for example by setting the environment variable OUTPUT_CHARSET
91       or by calling bind_textdomain_codeset()) and make sure that the system
92       locale also uses UTF-8, for example "en_US.UTF8".  If that fails,
93       switch to a locale that uses a subset of UTF-8.  In practice that will
94       be US-ASCII, the character set used by the default locale "C" resp.
95       "POSIX".
96
97       Your application will then to a certain extent mix output for different
98       localisations resp. languages.  But this is completely under your
99       control.
100

EXAMPLE

102       See above! Normally you should not use this module! However, let us
103       assume you have read the warnings.  In a web application you would do
104       something like this:
105
106           use Locale::TextDomain qw (com.example.yourapp);
107           use Locale::Messages qw (nl_putenv LC_ALL bindtextdomain
108                                    bind_textdomain_codeset);
109           use Locale::Util qw (web_set_locale);
110           use POSIX qw (setlocale);
111
112           # First try to switch to the locale requested by the user.  If you
113           # know it you can try to pass it to setlocale like this:
114           #
115           #   my $hardcoded_locale = 'fr_FR.UTF-8';
116           #   my $success = POSIX::setlocale (LC_ALL, $hardcoded_locale);
117           #
118           # However, we try to let libintl-perl do a better job for us:
119           my $success = web_set_locale $ENV{HTTP_ACCEPT_LANGUAGE},
120                                        $ENV{HTTP_ACCEPT_CHARSET};
121           # Note: If your application forces the use of UTF-8 for its output
122           # you should pass 'UTF-8' as the second argument to web_set_locale
123           # instead of $ENV{HTTP_ACCEPT_CHARSET}.
124
125           if (!$success) {
126               # Did not work.  Switch to the dumb interface of
127               # Locale::Messages.
128               Locale::Messages->select_package ('gettext_dumb');
129
130               # And try to switch to a default locale:
131               if (!setlocale (LC_ALL, 'en_US.UTF-8')) {
132                   # Still no luck.  Enforce at least US-ASCII:
133                   setlocale (LC_ALL, 'C');
134               }
135               bind_textdomain_codeset 'com.example.yourapp', 'utf-8';
136           }
137
138       If your application forces the usage of UTF-8 you should ignore the
139       environment variable
140

AUTHOR

142       Copyright (C) 2002-2017 Guido Flohr <http://www.guido-flohr.net/>
143       (<mailto:guido.flohr@cantanea.com>), all rights reserved.  See the
144       source code for details!code for details!
145

SEE ALSO

147       Locale::TextDomain(3pm), Locale::Messages(3pm), Encode(3pm),
148       perllocale(3pm), POSIX(3pm), perl(1), gettext(1), gettext(3)
149
150
151
152perl v5.36.0                      2023-01-20           Locale::gettext_dumb(3)
Impressum