.\" 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::Maketext::Gettext::Functions 3pm"
.TH Locale::Maketext::Gettext::Functions 3pm "2014-09-14" "perl v5.20.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::Maketext::Gettext::Functions \- Functional interface to Locale::Maketext::Gettext
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  use Locale::Maketext::Gettext::Functions;
\&  bindtextdomain(DOMAIN, LOCALEDIR);
\&  textdomain(DOMAIN);
\&  get_handle("de");
\&  print _\|_("Hello, world!\en");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Locale::Maketext::Gettext::Functions is a functional
interface to
\&\fILocale::Maketext::Gettext\fR\|(3) (and
\&\fILocale::Maketext\fR\|(3)).  It works exactly the \s-1GNU\s0
gettext way.  It plays magic to
\&\fILocale::Maketext\fR\|(3) for you.  No more
localization class/subclasses and language handles are required at
all.
.PP
The \f(CW\*(C`maketext\*(C'\fR, \f(CW\*(C`dmaketext\*(C'\fR, \f(CW\*(C`pmaketext\*(C'\fR and \f(CW\*(C`dpmaketext\*(C'\fR
functions attempt to translate a text message into the native
language of the user, by looking up the translation in an \s-1MO\s0 lexicon
file.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "bindtextdomain(\s-1DOMAIN, LOCALEDIR\s0)" 4
.IX Item "bindtextdomain(DOMAIN, LOCALEDIR)"
Register a text domain with a locale directory.  Returns \f(CW\*(C`LOCALEDIR\*(C'\fR
itself.  If \f(CW\*(C`LOCALEDIR\*(C'\fR is omitted, the registered locale directory
of \f(CW\*(C`DOMAIN\*(C'\fR is returned.  This method always success.
.IP "textdomain(\s-1DOMAIN\s0)" 4
.IX Item "textdomain(DOMAIN)"
Set the current text domain.  Returns the \f(CW\*(C`DOMAIN\*(C'\fR itself.  if
\&\f(CW\*(C`DOMAIN\*(C'\fR is omitted, the current text domain is returned.  This
method always success.
.IP "get_handle(@languages)" 4
.IX Item "get_handle(@languages)"
Set the language of the user.  It searches for an available language
in the provided \f(CW@languages\fR list.  If \f(CW@languages\fR was not provided, it
looks checks environment variable \s-1LANG,\s0 and \s-1HTTP_ACCEPT_LANGUAGE\s0
when running as \s-1CGI. \s0 Refer to
\&\fILocale::Maketext\fR\|(3) for the magic of the
\&\f(CW\*(C`get_handle\*(C'\fR.
.ie n .IP "$message = maketext($key, @param...)" 4
.el .IP "\f(CW$message\fR = maketext($key, \f(CW@param\fR...)" 4
.IX Item "$message = maketext($key, @param...)"
Attempts to translate a text message into the native language of the
user, by looking up the translation in an \s-1MO\s0 lexicon file.  Refer to
\&\fILocale::Maketext\fR\|(3) for the \f(CW\*(C`maketext\*(C'\fR plural
grammer.
.ie n .IP "$message = _\|_($key, @param...)" 4
.el .IP "\f(CW$message\fR = _\|_($key, \f(CW@param\fR...)" 4
.IX Item "$message = __($key, @param...)"
A synonym to \f(CW\*(C`maketext()\*(C'\fR.  This is a shortcut to \f(CW\*(C`maketext()\*(C'\fR so
that it is cleaner when you employ maketext to your existing project.
.ie n .IP "($key, @param...) = N_($key, @param...)" 4
.el .IP "($key, \f(CW@param\fR...) = N_($key, \f(CW@param\fR...)" 4
.IX Item "($key, @param...) = N_($key, @param...)"
Returns the original text untouched.  This is to enable the text be
catched with xgettext.
.ie n .IP "$message = dmaketext($domain, $key, @param...)" 4
.el .IP "\f(CW$message\fR = dmaketext($domain, \f(CW$key\fR, \f(CW@param\fR...)" 4
.IX Item "$message = dmaketext($domain, $key, @param...)"
Temporarily switch to another text domain and attempts to translate
a text message into the native language of the user in that text
domain.  Use \*(L"\-\-keyword=dmaketext:2\*(R" for the xgettext utility.
.ie n .IP "$message = pmaketext($ctxt, $key, @param...)" 4
.el .IP "\f(CW$message\fR = pmaketext($ctxt, \f(CW$key\fR, \f(CW@param\fR...)" 4
.IX Item "$message = pmaketext($ctxt, $key, @param...)"
Attempts to translate a text message in a particular context into the
native language of the user.  Use \*(L"\-\-keyword=pmaketext:1c,2\*(R" for
the xgettext utility.
.ie n .IP "$message = dpmaketext($domain, $ctxt, $key, @param...)" 4
.el .IP "\f(CW$message\fR = dpmaketext($domain, \f(CW$ctxt\fR, \f(CW$key\fR, \f(CW@param\fR...)" 4
.IX Item "$message = dpmaketext($domain, $ctxt, $key, @param...)"
Temporarily switch to another text domain and attempts to translate
a text message in a particular context into the native language of
the user in that text domain.  Use \*(L"\-\-keyword=dpmaketext:2c,3\*(R" for
the xgettext utility.
.IP "encoding(\s-1ENCODING\s0)" 4
.IX Item "encoding(ENCODING)"
Set or retrieve the output encoding.  The default is the same
encoding as the gettext \s-1MO\s0 file.  You can specify \f(CW\*(C`undef\*(C'\fR, to return
the result in unencoded \s-1UTF\-8.\s0
.IP "key_encoding(\s-1ENCODING\s0)" 4
.IX Item "key_encoding(ENCODING)"
Specify the encoding used in your original text.  The \f(CW\*(C`maketext\*(C'\fR
method itself is not multibyte-safe to the _AUTO lexicon.  If you are
using your native non-English language as your original text and you
are having troubles like:
.Sp
Unterminated bracket group, in:
.Sp
Then, specify the \f(CW\*(C`key_encoding\*(C'\fR to the encoding of your original
text.  Returns the current setting.
.Sp
\&\fB\s-1WARNING:\s0\fR You should always use US-ASCII text keys.  Using
non-US-ASCII keys is always discouraged and is not guaranteed to
be working.
.IP "encode_failure(\s-1CHECK\s0)" 4
.IX Item "encode_failure(CHECK)"
Set the action when encode fails.  This happens when the output text
is out of the scope of your output encoding.  For exmaple, output
Chinese into US-ASCII.  Refer to \fIEncode\fR\|(3) for the
possible values of this \f(CW\*(C`CHECK\*(C'\fR.  The default is \f(CW\*(C`FB_DEFAULT\*(C'\fR,
which is a safe choice that never fails.  But part of your text may
be lost, since that is what \f(CW\*(C`FB_DEFAULT\*(C'\fR does.  Returns the current
setting.
.IP "die_for_lookup_failures(\s-1SHOULD_I_DIE\s0)" 4
.IX Item "die_for_lookup_failures(SHOULD_I_DIE)"
Maketext dies for lookup failures, but \s-1GNU\s0 gettext never fails.
By default Lexicon::Maketext::Gettext follows the \s-1GNU\s0 gettext
behavior.  But if you are Maketext-styled, or if you need a better
control over the failures (like me :p), set this to 1.  Returns the
current setting.
.IP "\fIreload_text()\fR" 4
.IX Item "reload_text()"
Purges the \s-1MO\s0 text cache.  By default \s-1MO\s0 files are cached after they
are read and parsed from the disk, to reduce I/O and parsing overhead
on busy sites.  \fIreload_text()\fR purges this cache, so that updated \s-1MO\s0
files can take effect at run-time.  This is used when your \s-1MO\s0 file is
updated, but you cannot shutdown and restart the application.  for
example, when you are a co-hoster on a mod_perl\-enabled Apache, or
when your mod_perl\-enabled Apache is too vital to be restarted for
every update of your \s-1MO\s0 file, or if you are running a vital daemon,
such as an X display server.
.ie n .IP "%Lexicon = read_mo($MOfile)" 4
.el .IP "\f(CW%Lexicon\fR = read_mo($MOfile)" 4
.IX Item "%Lexicon = read_mo($MOfile)"
Read and parse the \s-1MO\s0 file.  Returns the read \f(CW%Lexicon\fR.  The returned
lexicon is in its original encoding.
.Sp
If you need the meta infomation of your \s-1MO\s0 file, parse the entry
\&\f(CW$Lexicon{""}\fR.  For example:
.Sp
.Vb 2
\&  /^Content\-Type: text\e/plain; charset=(.*)$/im;
\&  $encoding = $1;
.Ve
.SH "NOTES"
.IX Header "NOTES"
\&\fB\s-1NOTE:\s0\fR Since localization classes are generated at run-time, it is
not possible to override the Maketext language functions, like
\&\f(CW\*(C`quant\*(C'\fR or \f(CW\*(C`numerate\*(C'\fR.  If that is your concern, use
\&\fILocale::Maketext::Gettext\fR\|(3) instead.
Suggestions are welcome.
.PP
You can now add/remove languages/MO files at run-time.  This is a
major improvement over the original
\&\fILocale::Maketext::Gettext\fR\|(3) (and
\&\fILocale::Maketext\fR\|(3)).  This is done by
registering localization classes with random IDs, so that the same
text domain can be re-declared infinitely, whenever needed (language
list changes, \s-1LOCALEDIR\s0 changes, etc.)  This is not possible to the
object-interface of
\&\fILocale::Maketext::Gettext\fR\|(3) (and
\&\fILocale::Maketext\fR\|(3)).
.PP
Language addition/removal takes effect only after \f(CW\*(C`bindtextdomain\*(C'\fR
or \f(CW\*(C`textdomain\*(C'\fR is called.  It has no effect on \f(CW\*(C`maketext\*(C'\fR calls.
This keeps a basic sanity in the lifetime of a running script.
.PP
If you set \f(CW\*(C`textdomain\*(C'\fR to a domain that is not \f(CW\*(C`bindtextdomain\*(C'\fR to
specific a locale directory yet, it will try search system locale
directories.  The current system locale directory search order is:
/usr/share/locale, /usr/lib/locale, /usr/local/share/locale,
/usr/local/lib/locale.  Suggestions are welcome.
.SH "STORY"
.IX Header "STORY"
The idea is that:  I finally realized that, no matter how hard I try,
\&\fII can never get a never-failure \f(CI\*(C`maketext\*(C'\fI.\fR  A common wrapper
like:
.PP
.Vb 1
\&  sub _\|_ { return $LH\->maketext(@_) };
.Ve
.PP
always fails if \f(CW$LH\fR is not initialized yet.  For this reason, 
\&\f(CW\*(C`maketext\*(C'\fR can hardly be employed in error handlers to output
graceful error messages in the natural language of the user.  So,
I have to write something like this:
.PP
.Vb 4
\&  sub _\|_ {
\&      $LH = MyPkg::L10N\->get_handle if !defined $LH;
\&      return $LH\->maketext(@_);
\&  }
.Ve
.PP
But what if \f(CW\*(C`get_handle\*(C'\fR itself fails?  So, this becomes:
.PP
.Vb 10
\&  sub _\|_ {
\&      $LH = MyPkg::L10N\->get_handle if !defined $LH;
\&      $LH = _AUTO\->get_handle if !defined $LH;
\&      return $LH\->maketext(@_);
\&  }
\&  package _AUTO;
\&  use base qw(Locale::Maketext);
\&  package _AUTO::i_default;
\&  use base qw(Locale::Maketext);
\&  %Lexicon = ( "_AUTO" => 1 );
.Ve
.PP
Ya, this works.  But, if I always have to do this in my every
application, why should I not make a solution to the localization
framework itself?  This is a common problem to every localization
projects.  It should be solved at the localization framework level,
but not at the application level.
.PP
Another reason is that:  \fIProgrammers should be able to use
\&\f(CI\*(C`maketext\*(C'\fI without the knowledge of object-oriented programming.\fR
A localization framework should be neat and simple.  It should lower
down its barrier, be friendly to the beginners, in order to
encourage the use of localization and globalization.  Apparently
the current practice of \fILocale::Maketext\fR\|(3)
does not satisfy this request.
.PP
The third reason is:  Since 
\&\fILocale::Maketext::Gettext\fR\|(3) imports
the lexicon from foreign sources, the class source file is left
empty.  It exists only to help the \f(CW\*(C`get_handle\*(C'\fR method looking for
a proper language handle.  Then, why not make it disappear, and be
generated whenever needed?  Why bother the programmers to put
an empty class source file there?
.PP
How neat can we be?
.PP
imacat, 2003\-04\-29
.SH "BUGS"
.IX Header "BUGS"
Since maketext localization classes are generated at run time,
Maketext language function override, like \f(CW\*(C`quant\*(C'\fR or \f(CW\*(C`numerate\*(C'\fR, is
not available here.  Suggestions are welcome.
.PP
\&\f(CW\*(C`encoding\*(C'\fR, \f(CW\*(C`key_encoding\*(C'\fR, \f(CW\*(C`encode_failure\*(C'\fR and
\&\f(CW\*(C`die_for_lookup_failures\*(C'\fR are not mod_perl\-safe.  These settings
affect the whole process, including the following scripts it is
going to run.  This is the same as \f(CW\*(C`setlocale\*(C'\fR in
\&\s-1\fIPOSIX\s0\fR\|(3).  Always set them at the very beginning of your
script if you are running under mod_perl.  If you do not like it,
use the object-oriented
\&\fILocale::Maketext::Gettext\fR\|(3) instead.
Suggestions are welcome.
.PP
Smart translation between Traditional Chinese/Simplified Chinese,
like what \s-1GNU\s0 gettext does, is not available yet.  Suggestions are
welcome.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILocale::Maketext\fR\|(3),
\&\fILocale::Maketext::TPJ13\fR\|(3),
\&\fILocale::Maketext::Gettext\fR\|(3),
\&\fIbindtextdomain\fR\|(3), \fItextdomain\fR\|(3).
Also, please refer to the official \s-1GNU\s0 gettext manual at
<http://www.gnu.org/software/gettext/manual/>.
.SH "AUTHOR"
.IX Header "AUTHOR"
imacat <imacat@mail.imacat.idv.tw>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003\-2008 imacat. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.