.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Locale::Util 3pm"
.TH Locale::Util 3pm "2013-01-14" "perl v5.20.2" "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::Util \- Portable l10n and i10n functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Locale::Util;
\&
\&  my @linguas = parse_http_accept_language $ENV{HTTP_ACCEPT_LANGUAGE};
\&
\&  my @charsets = parse_http_accept_charset $ENV{HTTP_ACCEPT_CHARSET};
\&
\&  # Trie to set the locale to Brasilian Portuguese in UTF\-8.
\&  my $set_locale = set_locale LC_ALL, \*(Aqpt\*(Aq, \*(AqBR\*(Aq, \*(Aqutf\-8\*(Aq;
\&
\&  set_locale_cache $last_cache;
\&  
\&  my $cache = get_locale_cache;
\&
\&  web_set_locale ($ENV{HTTP_ACCEPT_LANGUAGE}, $ENV_ACCEPT_CHARSET);
\&
\&  web_set_locale ([\*(Aqfr\-BE\*(Aq, \*(Aqfr\*(Aq, \*(Aqit\*(Aq], [\*(Aqcp1252\*(Aq, \*(Aqutf\-8\*(Aq]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides portable functions dealing with localization
(l10n) and internationalization(i10n).  It doesn't export anything
by default, you have to specify each function you need in the import
list, or use the fully qualified name.
.PP
The functions here have a focus on web development, although they 
are general enough to have them in the Locale:: namespace.
.PP
This module is considered alpha code.  The interface is not stable.
Please contact the author if you want to use it in production code.
.PP
This module was introduced in libintl-perl 1.17.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBparse_http_accept_language \s-1STRING\s0\fR" 4
.IX Item "parse_http_accept_language STRING"
Parses a string as passed in the \s-1HTTP\s0 header \*(L"Accept-Language\*(R".
It returns a list of tokens sorted by the quality value, see \s-1RFC 2616 \s0
for details.
.Sp
Example:
.Sp
.Vb 1
\&  parse_http_accept ("fr\-fr, fr; q=0.7, de; q=0.3");
.Ve
.Sp
This means: Give me French for France with a quality value of 1.0
(the maximum).  Otherwise I will take any other French version 
(quality 0.7), German has a quality of 0.3 for me.
.Sp
The function will return a list of tokens in the order of their quality
values, in this case \*(L"fr-fr\*(R", \*(L"fr\*(R" and \*(L"de\*(R".
.Sp
The function is more forgiving than \s-1RFC 2616. \s0 It accepts quality
values greater than 1.0 and with more than 3 decimal places.  It
also accepts languages and country names with more than 8 characters.
The language \*(L"*\*(R" is translated into \*(L"C\*(R".
.IP "\fBparse_http_accept_charset \s-1STRING\s0\fR" 4
.IX Item "parse_http_accept_charset STRING"
Parses a string as passed in the \s-1HTTP\s0 header \*(L"Accept-Charset\*(R".
It returns a list of tokens sorted by the quality value, see \s-1RFC 2616 \s0
for details.
.Sp
The special character set \*(L"*\*(R" (means all character sets) will be
translated to the undefined value.
.IP "\fBset_locale \s-1CATEGORY,\s0 LANGUAGE[, \s-1COUNTRY, CHARSET\s0]\fR" 4
.IX Item "set_locale CATEGORY, LANGUAGE[, COUNTRY, CHARSET]"
Tries to set the user locale by means of \fIPOSIX::setlocale()\fR.  The latter
function has the disadvantage, that its second argument (the locale
description string) is completely non-standard and system-dependent.
This function tries its best at guessing the system's notion of a locale
dientifier, with the arguments supplied:
.RS 4
.IP "\fB\s-1CATEGORY\s0\fR" 8
.IX Item "CATEGORY"
An integer argument for a valid locale category.  These are the
LC_* constants (\s-1LC_ALL, LC_CTIME, LC_COLLATE, ...\s0) defined in both
\&\fILocale::Messages\fR\|(3pm) and \s-1\fIPOSIX\s0\fR\|(3pm).
.IP "\fB\s-1LANGUAGE\s0\fR" 8
.IX Item "LANGUAGE"
A 2\-letter language identifier as per \s-1ISO 639. \s0 Case doesn't matter,
but an unchanged version (ie. not lower-cased) of the language you
provided will always be tried to.
.IP "\fB\s-1COUNTRY\s0\fR" 8
.IX Item "COUNTRY"
A 2\-letter language identifier as per \s-1ISO 639. \s0 Case doesn't matter,
but an unchanged version (ie. not lower-cased) of the language you
provided will always be tried to.
.Sp
This parameter is optional.  If it is not defined, the function will
try to guess an appropriate country, otherwise leave it to the 
operating system.
.IP "\fB\s-1CHARSET\s0\fR" 8
.IX Item "CHARSET"
A valid charset name.  Valid means valid!  The charset \*(L"utf8\*(R" is not
valid (it is \*(L"utf\-8\*(R").  Charset names that are accepted by the
guessing algorithms in \fIEncode\fR\|(3pm) are also not necessarily valid.
.Sp
If the parameter is undefined, it is ignored.  It is always ignored
under Windows.
.RE
.RS 4
.Sp
The function tries to approach the desired locale in loops, refining
it on every success.  It will first try to set the language (for 
any country), then try to select the correct language, and finally
try to select the correct charset.
.Sp
The return value is false in case of failure, or the return value
of the underlying \fIPOSIX::setlocale()\fR call in case of success.
.Sp
In array context, the function returns the country name 
that was passed in the successful
call to \fIPOSIX::setlocale()\fR.  If this string is equal to the country
name you passed as an argument, you can be reasonably sure that
the settings for this country are really used.  If it is not
equal, the function has taken a guess at the country (it has a list
of \*(L"default\*(R" countries for each language).  It seems that under
Windows, \fIPOSIX::setlocale()\fR also succeeds, if you pass a country
name that is actually not supported.  Therefore, the information
is not completely reliable.
.Sp
Please note that this function is intended for server processes 
(especially web applications) that need to switch in a portable
way to a certain locale.  It is \fBnot\fR the recommended way to set 
the program locale for a regular application.  In a regular application
you should do the following:
.Sp
.Vb 2
\&    use POSIX qw (setlocale LC_ALL);
\&    setlocale LC_ALL, \*(Aq\*(Aq;
.Ve
.Sp
The empty string as the second argument means, that the system
should switch to the user's default locale.
.RE
.IP "\fBget_locale_cache\fR" 4
.IX Item "get_locale_cache"
The function \fIset_locale()\fR is potentially expansive, especially when
it fails, because it can try a lot of different combinations, and 
the system may have to load a lot of locale definitions from its
internal database.
.Sp
In order to speed up things, results are internally cached in a 
hash, keys are the languages, subkeys countries, subsubkeys the
charsets.  You can get a reference to this hash with \fIget_locale_cache()\fR.
.Sp
The function cannot fail.
.IP "\fBset_locale_cache \s-1HASH\s0\fR" 4
.IX Item "set_locale_cache HASH"
Sets the internal cache.  You can either pass a hash or a hash reference.
The function will use this as its cache, discarding its old cache.
This allows you to keep the hash persistent.
.Sp
The function cannot fail.
.IP "\fBweb_set_locale (\s-1ACCEPT_LANGUAGE, ACCEPT_CHARSET, CATEGORY, AVAILABLE\s0)\fR" 4
.IX Item "web_set_locale (ACCEPT_LANGUAGE, ACCEPT_CHARSET, CATEGORY, AVAILABLE)"
Try to change the locale to the settings described by \s-1ACCEPT_LANGUAGE\s0
and \s-1ACCEPT_CHARSET. \s0 For each argument you can either pass a string
as in the corresponding http header, or a reference to an array
of language resp. charset identifiers.
.Sp
Currently only the first charset passed is used as an argument.
You are strongly encouraged to pass a hard-coded value here, so
that you have control about your output.
.Sp
The argument \fB\s-1CATEGORY\s0\fR specifies the category (one of the LC_*
constants as defined in \fILocale::Messages\fR\|(3pm) or in \s-1\fIPOSIX\s0\fR\|(3pm)).
The category defaults to \s-1LC_ALL.\s0
.Sp
You can pass an optional reference to a list of locales in 
\&\s-1XPG4\s0 format that are available in your application.  This is
useful if you know which languages are supported by your application.
In fact, only the language part of the values in the list are
considered (for example for \*(L"en_US\*(R", only \*(L"en\*(R" is used).  The
country or other parts are ignored.
.Sp
The function returns the return value of the underlying \fIset_locale()\fR
call, or false on failure.
.Sp
The function returns false on failure.  On success it returns the 
return value of the underlying \fIset_locale()\fR call.  This value can
be used directly in subsequent calls to \fIPOSIX::setlocale()\fR.  In 
array context, it additionally returns the identifiers for the language, 
the country, and the charset actually used.
.SH "BUGS"
.IX Header "BUGS"
The function \fIset_locale()\fR probably fails to guess the correct locale
identifier on a lot of systems.  If you have found such a case,
please submit it as a bug report.
.PP
The bug tracking system for this packags is at
http://rt.cpan.org/NoAuth/Bugs.html?libintl\-perl
.PP
Please note that this module is considered alpha code, and the interface
is not stable.  Please contact the author, if you want to use it in
production code.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) 2002\-2013, Guido Flohr <guido@imperia.net>, all
rights reserved.  See the source code for details.
.PP
This software is contributed to the Perl community by Imperia 
(<http://www.imperia.net/>).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fIPOSIX\s0\fR\|(3pm), \fIperl\fR\|(1)
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 1213:" 4
.IX Item "Around line 1213:"
=cut found outside a pod block.  Skipping to next block.