.\" 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 3pm"
.TH Locale::Maketext::Gettext 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 \- Joins the gettext and Maketext frameworks
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In your localization class:
.PP
.Vb 3
\&  package MyPackage::L10N;
\&  use base qw(Locale::Maketext::Gettext);
\&  return 1;
.Ve
.PP
In your application:
.PP
.Vb 5
\&  use MyPackage::L10N;
\&  $LH = MyPackage::L10N\->get_handle or die "What language?";
\&  $LH\->bindtextdomain("mypackage", "/home/user/locale");
\&  $LH\->textdomain("mypackage");
\&  $LH\->maketext("Hello, world!!");
.Ve
.PP
If you want to have more control to the detail:
.PP
.Vb 10
\&  # Change the output encoding
\&  $LH\->encoding("UTF\-8");
\&  # Stick with the Maketext behavior on lookup failures
\&  $LH\->die_for_lookup_failures(1);
\&  # Flush the MO file cache and re\-read your updated MO files
\&  $LH\->reload_text;
\&  # Set the encoding of your maketext keys, if not in English
\&  $LH\->key_encoding("Big5");
\&  # Set the action when encode fails
\&  $LH\->encode_failure(Encode::FB_HTMLCREF);
.Ve
.PP
Use Locale::Maketext::Gettext to read and parse the \s-1MO\s0 file:
.PP
.Vb 2
\&  use Locale::Maketext::Gettext;
\&  %Lexicon = read_mo($MOfile);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Locale::Maketext::Gettext joins the \s-1GNU\s0 gettext and Maketext
frameworks.  It is a subclass of \fILocale::Maketext\fR\|(3)
that follows the way \s-1GNU\s0 gettext works.  It works seamlessly, \fIboth
in the sense of \s-1GNU\s0 gettext and Maketext\fR.  As a result, you \fIenjoy
both their advantages, and get rid of both their problems, too.\fR
.PP
You start as an usual \s-1GNU\s0 gettext localization project:  Work on
\&\s-1PO\s0 files with the help of translators, reviewers and Emacs.  Turn
them into \s-1MO\s0 files with \fImsgfmt\fR.  Copy them into the appropriate
locale directory, such as
\&\fI/usr/share/locale/de/LC_MESSAGES/myapp.mo\fR.
.PP
Then, build your Maketext localization class, with your base class
changed from \fILocale::Maketext\fR\|(3) to
Locale::Maketext::Gettext.  That is all.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "$LH\->bindtextdomain(\s-1DOMAIN, LOCALEDIR\s0)" 4
.el .IP "\f(CW$LH\fR\->bindtextdomain(\s-1DOMAIN, LOCALEDIR\s0)" 4
.IX Item "$LH->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.
.ie n .IP "$LH\->textdomain(\s-1DOMAIN\s0)" 4
.el .IP "\f(CW$LH\fR\->textdomain(\s-1DOMAIN\s0)" 4
.IX Item "$LH->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.
.ie n .IP "$text = $LH\->maketext($key, @param...)" 4
.el .IP "\f(CW$text\fR = \f(CW$LH\fR\->maketext($key, \f(CW@param\fR...)" 4
.IX Item "$text = $LH->maketext($key, @param...)"
Lookup the \f(CW$key\fR in the current lexicon and return a translated
message in the language of the user.  This is the same method in
\&\fILocale::Maketext\fR\|(3), with a wrapper that
returns the text message \f(CW\*(C`encode\*(C'\fRd according to the current
\&\f(CW\*(C`encoding\*(C'\fR.  Refer to \fILocale::Maketext\fR\|(3) for
the maketext plural notation.
.ie n .IP "$text = $LH\->pmaketext($ctxt, $key, @param...)" 4
.el .IP "\f(CW$text\fR = \f(CW$LH\fR\->pmaketext($ctxt, \f(CW$key\fR, \f(CW@param\fR...)" 4
.IX Item "$text = $LH->pmaketext($ctxt, $key, @param...)"
Lookup the \f(CW$key\fR in a particular context in the current lexicon and
return a translated message in the language of the user.   Use
\&\*(L"\-\-keyword=pmaketext:1c,2\*(R" for the xgettext utility.
.ie n .IP "$LH\->language_tag" 4
.el .IP "\f(CW$LH\fR\->language_tag" 4
.IX Item "$LH->language_tag"
Retrieve the language tag.  This is the same method in
\&\fILocale::Maketext\fR\|(3).  It is readonly.
.ie n .IP "$LH\->encoding(\s-1ENCODING\s0)" 4
.el .IP "\f(CW$LH\fR\->encoding(\s-1ENCODING\s0)" 4
.IX Item "$LH->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
.ie n .IP "$LH\->key_encoding(\s-1ENCODING\s0)" 4
.el .IP "\f(CW$LH\fR\->key_encoding(\s-1ENCODING\s0)" 4
.IX Item "$LH->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.
.ie n .IP "$LH\->encode_failure(\s-1CHECK\s0)" 4
.el .IP "\f(CW$LH\fR\->encode_failure(\s-1CHECK\s0)" 4
.IX Item "$LH->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.
.ie n .IP "$LH\->die_for_lookup_failures(\s-1SHOULD_I_DIE\s0)" 4
.el .IP "\f(CW$LH\fR\->die_for_lookup_failures(\s-1SHOULD_I_DIE\s0)" 4
.IX Item "$LH->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.
.Sp
Note that lookup failure handler you registered with \fIfail_with()\fR only
work when \fIdie_for_lookup_failures()\fR is enabled.  if you disable
\&\fIdie_for_lookup_failures()\fR, \fImaketext()\fR never fails and lookup failure
handler will be ignored.
.ie n .IP "$LH\->reload_text" 4
.el .IP "\f(CW$LH\fR\->reload_text" 4
.IX Item "$LH->reload_text"
Purge the \s-1MO\s0 text cache.  It purges the \s-1MO\s0 text cache from the base
class Locale::Maketext::Gettext.  The next time \f(CW\*(C`maketext\*(C'\fR is
called, the \s-1MO\s0 file will be read and parse from the disk again.  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.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.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
.Sp
\&\f(CW\*(C`read_mo()\*(C'\fR is exported by default, but you need to \f(CW\*(C`use
Locale::Maketext::Gettext\*(C'\fR in order to use it.  It is not exported
from your localization class, but from the Locale::Maketext::Gettext
package.
.SH "NOTES"
.IX Header "NOTES"
\&\fB\s-1WARNING:\s0\fR do not try to put any lexicon in your language subclass.
When the \f(CW\*(C`textdomain\*(C'\fR method is called, the current lexicon will be
\&\fBreplaced\fR, but not appended.  This is to accommodate the way
\&\f(CW\*(C`textdomain\*(C'\fR works.  Messages from the previous text domain should
not stay in the current text domain.
.PP
An essential benefit of this Locale::Maketext::Gettext over the
original \fILocale::Maketext\fR\|(3) is that: 
\&\fI\s-1GNU\s0 gettext is multibyte safe,\fR but Perl source is not.  \s-1GNU\s0 gettext
is safe to Big5 characters like \exa5\ex5c (Gong1).  But if you follow
the current \fILocale::Maketext\fR\|(3) document and
put your lexicon as a hash in the source of a localization subclass,
you have to escape bytes like \ex5c, \ex40, \ex5b, etc., in the middle
of some natural multibyte characters.  This breaks these characters
in halves.  Your non-technical translators and reviewers will be
presented with unreadable mess, \*(L"Luan4Ma3\*(R".  Sorry to say this, but
it is weird for a localization framework to be not multibyte-safe.
But, well, here comes Locale::Maketext::Gettext to rescue.  With
Locale::Maketext::Gettext, you can sit back and relax now, leaving
all this mess to the excellent \s-1GNU\s0 gettext framework.
.PP
The idea of Locale::Maketext::Getttext came from
\&\fILocale::Maketext::Lexicon\fR\|(3), a great
work by Autrijus.  But it has several problems at that time (version
0.16).  I was first trying to write a wrapper to fix it, but finally
I dropped it and decided to make a solution towards
\&\fILocale::Maketext\fR\|(3) itself.
\&\fILocale::Maketext::Lexicon\fR\|(3) should be
fine now if you obtain a version newer than 0.16.
.PP
Locale::Maketext::Gettext also solved the problem of lack of the
ability to handle the encoding in
\&\fILocale::Maketext\fR\|(3).  I implement this since
this is what \s-1GNU\s0 gettext does.  When \f(CW%Lexicon\fR is read from \s-1MO\s0 files
by \f(CW\*(C`read_mo()\*(C'\fR, the encoding tagged in gettext \s-1MO\s0 files is used to
\&\f(CW\*(C`decode\*(C'\fR the text into the internal encoding of Perl.  Then, when
extracted by \f(CW\*(C`maketext\*(C'\fR, it is \f(CW\*(C`encode\*(C'\fRd by the current
\&\f(CW\*(C`encoding\*(C'\fR value.  The \f(CW\*(C`encoding\*(C'\fR can be set at run time, so
that you can run a daemon and output to different encoding
according to the language settings of individual users, without
having to restart the application.  This is an improvement to the
\&\fILocale::Maketext\fR\|(3), and is essential to
daemons and \f(CW\*(C`mod_perl\*(C'\fR applications.
.PP
You should trust the encoding of your gettext \s-1MO\s0 file.  \s-1GNU\s0 gettext
\&\f(CW\*(C`msgfmt\*(C'\fR checks the illegal characters for you when you compile your
\&\s-1MO\s0 file from your \s-1PO\s0 file.  The encoding form your \s-1MO\s0 files are
always good.  If you try to output to a wrong encoding, part of your
text may be lost, as \f(CW\*(C`FB_DEFAULT\*(C'\fR does.  If you do not like this
\&\f(CW\*(C`FB_DEFAULT\*(C'\fR, change the failure behavior with the method
\&\f(CW\*(C`encode_failure\*(C'\fR.
.PP
If you need the behavior of auto Traditional Chinese/Simplfied
Chinese conversion, as \s-1GNU\s0 gettext smartly does, do it yourself with
\&\fIEncode::HanExtra\fR\|(3), too.  There may be a
solution for this in the future, but not now.
.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 for this search order are
welcome.
.PP
\&\fB\s-1NOTICE:\s0\fR \fIMyPackage::L10N::en\->maketext(...) is not available
anymore,\fR as the \f(CW\*(C`maketext\*(C'\fR method is no more static.  That is a
sure result, as \f(CW%Lexicon\fR is imported from foreign sources
dynamically, but not statically hardcoded in Perl sources.  But the
documentation of \fILocale::Maketext\fR\|(3) does not
say that you can use it as a static method anyway.  Maybe you were
practicing this before.  You had better check your existing code for
this.  If you try to invoke it statically, it returns \f(CW\*(C`undef\*(C'\fR.
.PP
\&\f(CW\*(C`dgettext\*(C'\fR and \f(CW\*(C`dcgettext\*(C'\fR in \s-1GNU\s0 gettext are not implemented.
It is not possible to temporarily change the current text domain in
the current design of Locale::Maketext::Gettext.  Besides, it is
meaningless.  Locale::Maketext is object-oriented.  You can always
raise a new language handle for another text domain.  This is
different from the situation of \s-1GNU\s0 gettext.  Also, the category
is always \f(CW\*(C`LC_MESSAGES\*(C'\fR.  Of course it is.  We are gettext and
Maketext.
.PP
Avoid creating different language handles with different
textdomain on the same localization subclass.  This currently
works, but it violates the basic design of 
\&\fILocale::Maketext\fR\|(3).  In
\&\fILocale::Maketext\fR\|(3), \f(CW%Lexicon\fR is saved as a
class variable, in order for the lexicon inheritance system to work.
So, multiple language handles to a same localization subclass shares
a same lexicon space.  Their lexicon space clash.  I tried to avoid
this problem by saving a copy of the current lexicon as an instance
variable, and replacing the class lexicon with the current instance
lexicon whenever it is changed by another language handle instance.
But this involves large scaled memory copy, which affects the
proformance seriously.  This is discouraged.  You are advised to use
a single textdomain for a single localization class.
.PP
The \f(CW\*(C`key_encoding\*(C'\fR is a workaround, not a solution.  There is no
solution to this problem yet.  You should avoid using non-English
language as your original text.  You will get yourself into trouble
if you mix several original text encodings, for example, joining
several pieces of code from programmers all around the world, with
their messages written in their own language and encodings.  Solution
suggestions are welcome.
.PP
\&\f(CW\*(C`pgettext\*(C'\fR in \s-1GNU\s0 gettext is implemented as \f(CW\*(C`pmaketext\*(C'\fR, in order
to look up the text message translation in a particular context.
Thanks to the suggestion from Chris Travers.
.SH "BUGS"
.IX Header "BUGS"
\&\s-1GNU\s0 gettext never fails.  I tries to achieve it as long as possible.
The only reason that maketext may die unexpectedly now is
\&\*(L"Unterminated bracket group\*(R".  I cannot get a better solution to it
currently.  Suggestions are welcome.
.PP
You are welcome to fix my English.  I have done my best to this
documentation, but I am not a native English speaker after all. ^^;
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILocale::Maketext\fR\|(3),
\&\fILocale::Maketext::TPJ13\fR\|(3),
\&\fILocale::Maketext::Lexicon\fR\|(3),
\&\fIEncode\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.