1Locale::Util(3)       User Contributed Perl Documentation      Locale::Util(3)
2
3
4

NAME

6       Locale::Util - Portable l10n and i10n functions
7

SYNOPSIS

9         use Locale::Util;
10
11         my @linguas = parse_http_accept_language $ENV{HTTP_ACCEPT_LANGUAGE};
12
13         my @charsets = parse_http_accept_charset $ENV{HTTP_ACCEPT_CHARSET};
14
15         # Trie to set the locale to Brasilian Portuguese in UTF-8.
16         my $set_locale = set_locale LC_ALL, 'pt', 'BR', 'utf-8';
17
18         set_locale_cache $last_cache;
19
20         my $cache = get_locale_cache;
21
22         web_set_locale ($ENV{HTTP_ACCEPT_LANGUAGE}, $ENV_ACCEPT_CHARSET);
23
24         web_set_locale (['fr-BE', 'fr', 'it'], ['cp1252', 'utf-8']);
25

DESCRIPTION

27       This module provides portable functions dealing with localization
28       (l10n) and internationalization(i10n).  It doesn't export anything by
29       default, you have to specify each function you need in the import list,
30       or use the fully qualified name.
31
32       The functions here have a focus on web development, although they are
33       general enough to have them in the Locale:: namespace.
34
35       This module is considered alpha code.  The interface is not stable.
36       Please contact the author if you want to use it in production code.
37
38       This module was introduced in libintl-perl 1.17.
39

FUNCTIONS

41       parse_http_accept_language STRING
42           Parses a string as passed in the HTTP header "Accept-Language".  It
43           returns a list of tokens sorted by the quality value, see RFC 2616
44           for details.
45
46           Example:
47
48             parse_http_accept ("fr-fr, fr; q=0.7, de; q=0.3");
49
50           This means: Give me French for France with a quality value of 1.0
51           (the maximum).  Otherwise I will take any other French version
52           (quality 0.7), German has a quality of 0.3 for me.
53
54           The function will return a list of tokens in the order of their
55           quality values, in this case "fr-fr", "fr" and "de".
56
57           The function is more forgiving than RFC 2616.  It accepts quality
58           values greater than 1.0 and with more than 3 decimal places.  It
59           also accepts languages and country names with more than 8
60           characters.  The language "*" is translated into "C".
61
62       parse_http_accept_charset STRING
63           Parses a string as passed in the HTTP header "Accept-Charset".  It
64           returns a list of tokens sorted by the quality value, see RFC 2616
65           for details.
66
67           The special character set "*" (means all character sets) will be
68           translated to the undefined value.
69
70       set_locale CATEGORY, LANGUAGE[, COUNTRY, CHARSET]
71           Tries to set the user locale by means of POSIX::setlocale().  The
72           latter function has the disadvantage, that its second argument (the
73           locale description string) is completely non-standard and system-
74           dependent.  This function tries its best at guessing the system's
75           notion of a locale dientifier, with the arguments supplied:
76
77           CATEGORY
78                   An integer argument for a valid locale category.  These are
79                   the LC_* constants (LC_ALL, LC_CTIME, LC_COLLATE, ...)
80                   defined in both Locale::Messages(3pm) and POSIX(3pm).
81
82           LANGUAGE
83                   A 2-letter language identifier as per ISO 639.  Case
84                   doesn't matter, but an unchanged version (ie. not lower-
85                   cased) of the language you provided will always be tried
86                   to.
87
88           COUNTRY A 2-letter language identifier as per ISO 639.  Case
89                   doesn't matter, but an unchanged version (ie. not lower-
90                   cased) of the language you provided will always be tried
91                   to.
92
93                   This parameter is optional.  If it is not defined, the
94                   function will try to guess an appropriate country,
95                   otherwise leave it to the operating system.
96
97           CHARSET A valid charset name.  Valid means valid!  The charset
98                   "utf8" is not valid (it is "utf-8").  Charset names that
99                   are accepted by the guessing algorithms in Encode(3pm) are
100                   also not necessarily valid.
101
102                   If the parameter is undefined, it is ignored.  It is always
103                   ignored under Windows.
104
105           The function tries to approach the desired locale in loops,
106           refining it on every success.  It will first try to set the
107           language (for any country), then try to select the correct
108           language, and finally try to select the correct charset.
109
110           The return value is false in case of failure, or the return value
111           of the underlying POSIX::setlocale() call in case of success.
112
113           In array context, the function returns the country name that was
114           passed in the successful call to POSIX::setlocale().  If this
115           string is equal to the country name you passed as an argument, you
116           can be reasonably sure that the settings for this country are
117           really used.  If it is not equal, the function has taken a guess at
118           the country (it has a list of "default" countries for each
119           language).  It seems that under Windows, POSIX::setlocale() also
120           succeeds, if you pass a country name that is actually not
121           supported.  Therefore, the information is not completely reliable.
122
123           Please note that this function is intended for server processes
124           (especially web applications) that need to switch in a portable way
125           to a certain locale.  It is not the recommended way to set the
126           program locale for a regular application.  In a regular application
127           you should do the following:
128
129               use POSIX qw (setlocale LC_ALL);
130               setlocale LC_ALL, '';
131
132           The empty string as the second argument means, that the system
133           should switch to the user's default locale.
134
135       get_locale_cache
136           The function set_locale() is potentially expansive, especially when
137           it fails, because it can try a lot of different combinations, and
138           the system may have to load a lot of locale definitions from its
139           internal database.
140
141           In order to speed up things, results are internally cached in a
142           hash, keys are the languages, subkeys countries, subsubkeys the
143           charsets.  You can get a reference to this hash with
144           get_locale_cache().
145
146           The function cannot fail.
147
148       set_locale_cache HASH
149           Sets the internal cache.  You can either pass a hash or a hash
150           reference.  The function will use this as its cache, discarding its
151           old cache.  This allows you to keep the hash persistent.
152
153           The function cannot fail.
154
155       web_set_locale (ACCEPT_LANGUAGE, ACCEPT_CHARSET, CATEGORY, AVAILABLE)
156           Try to change the locale to the settings described by
157           ACCEPT_LANGUAGE and ACCEPT_CHARSET.  For each argument you can
158           either pass a string as in the corresponding http header, or a
159           reference to an array of language resp. charset identifiers.
160
161           Currently only the first charset passed is used as an argument.
162           You are strongly encouraged to pass a hard-coded value here, so
163           that you have control about your output.
164
165           The argument CATEGORY specifies the category (one of the LC_*
166           constants as defined in Locale::Messages(3pm) or in POSIX(3pm)).
167           The category defaults to LC_ALL.
168
169           You can pass an optional reference to a list of locales in XPG4
170           format that are available in your application.  This is useful if
171           you know which languages are supported by your application.  In
172           fact, only the language part of the values in the list are
173           considered (for example for "en_US", only "en" is used).  The
174           country or other parts are ignored.
175
176           The function returns the return value of the underlying
177           set_locale() call, or false on failure.
178
179           The function returns false on failure.  On success it returns the
180           return value of the underlying set_locale() call.  This value can
181           be used directly in subsequent calls to POSIX::setlocale().  In
182           array context, it additionally returns the identifiers for the
183           language, the country, and the charset actually used.
184

BUGS

186       The function set_locale() probably fails to guess the correct locale
187       identifier on a lot of systems.  If you have found such a case, please
188       submit it as a bug report.
189
190       The bug tracking system for this packags is at
191       http://rt.cpan.org/NoAuth/Bugs.html?libintl-perl
192
193       Please note that this module is considered alpha code, and the
194       interface is not stable.  Please contact the author, if you want to use
195       it in production code.
196

AUTHOR

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

SEE ALSO

203       POSIX(3pm), perl(1)
204
205
206
207perl v5.38.0                      2023-07-21                   Locale::Util(3)
Impressum