1Locale::Maketext::GetteUxste(r3)Contributed Perl DocumenLtoactailoen::Maketext::Gettext(3)
2
3
4

NAME

6       Locale::Maketext::Gettext - Joins the gettext and Maketext frameworks
7

SYNOPSIS

9       In your localization class:
10
11         package MyPackage::L10N;
12         use base qw(Locale::Maketext::Gettext);
13         return 1;
14
15       In your application:
16
17         use MyPackage::L10N;
18         $LH = MyPackage::L10N->get_handle or die "What language?";
19         $LH->bindtextdomain("mypackage", "/home/user/locale");
20         $LH->textdomain("mypackage");
21         $LH->maketext("Hello, world!!");
22
23       If you want to have more control to the detail:
24
25         # Change the output encoding
26         $LH->encoding("UTF-8");
27         # Stick with the Maketext behavior on lookup failures
28         $LH->die_for_lookup_failures(1);
29         # Flush the MO file cache and re-read your updated MO files
30         $LH->reload_text;
31         # Set the encoding of your maketext keys, if not in English
32         $LH->key_encoding("Big5");
33         # Set the action when encode fails
34         $LH->encode_failure(Encode::FB_HTMLCREF);
35
36       Use Locale::Maketext::Gettext to read and parse the MO file:
37
38         use Locale::Maketext::Gettext;
39         %Lexicon = read_mo($mo_file);
40

DESCRIPTION

42       Locale::Maketext::Gettext joins the GNU gettext and Maketext
43       frameworks.  It is a subclass of Locale::Maketext(3) that follows the
44       way GNU gettext works.  It works seamlessly, both in the sense of GNU
45       gettext and Maketext.  As a result, you enjoy both their advantages,
46       and get rid of both their problems, too.
47
48       You start as an usual GNU gettext localization project:  Work on PO
49       files with the help of translators, reviewers and Emacs.  Turn them
50       into MO files with msgfmt.  Copy them into the appropriate locale
51       directory, such as /usr/share/locale/de/LC_MESSAGES/myapp.mo.
52
53       Then, build your Maketext localization class, with your base class
54       changed from Locale::Maketext(3) to Locale::Maketext::Gettext.  That is
55       all.
56

METHODS

58       $LH->bindtextdomain(DOMAIN, LOCALEDIR)
59           Register a text domain with a locale directory.  Returns
60           "LOCALEDIR" itself.  If "LOCALEDIR" is omitted, the registered
61           locale directory of "DOMAIN" is returned.  This method always
62           success.
63
64       $LH->textdomain(DOMAIN)
65           Set the current text domain.  Returns the "DOMAIN" itself.  If
66           "DOMAIN" is omitted, the current text domain is returned.  This
67           method always success.
68
69       $text = $LH->maketext($key, @param...)
70           Lookup the $key in the current lexicon and return a translated
71           message in the language of the user.  This is the same method in
72           Locale::Maketext(3), with a wrapper that returns the text message
73           "encode"d according to the current "encoding".  Refer to
74           Locale::Maketext(3) for the maketext plural notation.
75
76       $text = $LH->pmaketext($ctxt, $key, @param...)
77           Lookup the $key in a particular context in the current lexicon and
78           return a translated message in the language of the user.   Use
79           "--keyword=pmaketext:1c,2" for the xgettext utility.
80
81       $LH->language_tag
82           Retrieve the language tag.  This is the same method in
83           Locale::Maketext(3).  It is readonly.
84
85       $LH->encoding(ENCODING)
86           Set or retrieve the output encoding.  The default is the same
87           encoding as the gettext MO file.  You can specify "undef", to
88           return the result in unencoded UTF-8.
89
90       $LH->key_encoding(ENCODING)
91           Specify the encoding used in your original text.  The "maketext"
92           method itself is not multibyte-safe to the _AUTO lexicon.  If you
93           are using your native non-English language as your original text
94           and you are having troubles like:
95
96           Unterminated bracket group, in:
97
98           Then, specify the "key_encoding" to the encoding of your original
99           text.  Returns the current setting.
100
101           WARNING: You should always use US-ASCII text keys.  Using non-US-
102           ASCII keys is always discouraged and is not guaranteed to be
103           working.
104
105       $LH->encode_failure(CHECK)
106           Set the action when encode fails.  This happens when the output
107           text is out of the scope of your output encoding.  For exmaple,
108           output Chinese into US-ASCII.  Refer to Encode(3) for the possible
109           values of this "CHECK".  The default is "FB_DEFAULT", which is a
110           safe choice that never fails.  But part of your text may be lost,
111           since that is what "FB_DEFAULT" does.  Returns the current setting.
112
113       $LH->die_for_lookup_failures(SHOULD_I_DIE)
114           Maketext dies for lookup failures, but GNU gettext never fails.  By
115           default Lexicon::Maketext::Gettext follows the GNU gettext
116           behavior.  But if you are Maketext-styled, or if you need a better
117           control over the failures (like me :p), set this to 1.  Returns the
118           current setting.
119
120           Note that lookup failure handler you registered with fail_with()
121           only work when die_for_lookup_failures() is enabled.  if you
122           disable die_for_lookup_failures(), maketext() never fails and
123           lookup failure handler will be ignored.
124
125       $LH->reload_text
126           Purge the MO text cache.  It purges the MO text cache from the base
127           class Locale::Maketext::Gettext.  The next time "maketext" is
128           called, the MO file will be read and parse from the disk again.
129           This is used when your MO file is updated, but you cannot shutdown
130           and restart the application.  For example, when you are a co-hoster
131           on a mod_perl-enabled Apache, or when your mod_perl-enabled Apache
132           is too vital to be restarted for every update of your MO file, or
133           if you are running a vital daemon, such as an X display server.
134

FUNCTIONS

136       %Lexicon = read_mo($mo_file);
137           Read and parse the MO file.  Returns the read %Lexicon.  The
138           returned lexicon is in its original encoding.
139
140           If you need the meta infomation of your MO file, parse the entry
141           $Lexicon{""}.  For example:
142
143             /^Content-Type: text\/plain; charset=(.*)$/im;
144             $encoding = $1;
145
146           "read_mo()" is exported by default, but you need to "use
147           Locale::Maketext::Gettext" in order to use it.  It is not exported
148           from your localization class, but from the
149           Locale::Maketext::Gettext package.
150

NOTES

152       WARNING: do not try to put any lexicon in your language subclass.  When
153       the "textdomain" method is called, the current lexicon will be
154       replaced, but not appended.  This is to accommodate the way
155       "textdomain" works.  Messages from the previous text domain should not
156       stay in the current text domain.
157
158       An essential benefit of this Locale::Maketext::Gettext over the
159       original Locale::Maketext(3) is that: GNU gettext is multibyte safe,
160       but Perl source is not.  GNU gettext is safe to Big5 characters like
161       \xa5\x5c (Gong1).  But if you follow the current Locale::Maketext(3)
162       document and put your lexicon as a hash in the source of a localization
163       subclass, you have to escape bytes like \x5c, \x40, \x5b, etc., in the
164       middle of some natural multibyte characters.  This breaks these
165       characters in halves.  Your non-technical translators and reviewers
166       will be presented with unreadable mess, "Luan4Ma3".  Sorry to say this,
167       but it is weird for a localization framework to be not multibyte-safe.
168       But, well, here comes Locale::Maketext::Gettext to rescue.  With
169       Locale::Maketext::Gettext, you can sit back and relax now, leaving all
170       this mess to the excellent GNU gettext framework.
171
172       The idea of Locale::Maketext::Getttext came from
173       Locale::Maketext::Lexicon(3), a great work by Autrijus.  But it has
174       several problems at that time (version 0.16).  I was first trying to
175       write a wrapper to fix it, but finally I dropped it and decided to make
176       a solution towards Locale::Maketext(3) itself.
177       Locale::Maketext::Lexicon(3) should be fine now if you obtain a version
178       newer than 0.16.
179
180       Locale::Maketext::Gettext also solved the problem of lack of the
181       ability to handle the encoding in Locale::Maketext(3).  I implement
182       this since this is what GNU gettext does.  When %Lexicon is read from
183       MO files by "read_mo()", the encoding tagged in gettext MO files is
184       used to "decode" the text into the internal encoding of Perl.  Then,
185       when extracted by "maketext", it is "encode"d by the current "encoding"
186       value.  The "encoding" can be set at run time, so that you can run a
187       daemon and output to different encoding according to the language
188       settings of individual users, without having to restart the
189       application.  This is an improvement to the Locale::Maketext(3), and is
190       essential to daemons and "mod_perl" applications.
191
192       You should trust the encoding of your gettext MO file.  GNU gettext
193       "msgfmt" checks the illegal characters for you when you compile your MO
194       file from your PO file.  The encoding form your MO files are always
195       good.  If you try to output to a wrong encoding, part of your text may
196       be lost, as "FB_DEFAULT" does.  If you do not like this "FB_DEFAULT",
197       change the failure behavior with the method "encode_failure".
198
199       If you need the behavior of auto Traditional Chinese/Simplfied Chinese
200       conversion, as GNU gettext smartly does, do it yourself with
201       Encode::HanExtra(3), too.  There may be a solution for this in the
202       future, but not now.
203
204       If you set "textdomain" to a domain that is not "bindtextdomain" to
205       specific a locale directory yet, it will try search system locale
206       directories.  The current system locale directory search order is:
207       /usr/share/locale, /usr/lib/locale, /usr/local/share/locale,
208       /usr/local/lib/locale.  Suggestions for this search order are welcome.
209
210       NOTICE: MyPackage::L10N::en->maketext(...) is not available anymore, as
211       the "maketext" method is no more static.  That is a sure result, as
212       %Lexicon is imported from foreign sources dynamically, but not
213       statically hardcoded in Perl sources.  But the documentation of
214       Locale::Maketext(3) does not say that you can use it as a static method
215       anyway.  Maybe you were practicing this before.  You had better check
216       your existing code for this.  If you try to invoke it statically, it
217       returns "undef".
218
219       "dgettext" and "dcgettext" in GNU gettext are not implemented.  It is
220       not possible to temporarily change the current text domain in the
221       current design of Locale::Maketext::Gettext.  Besides, it is
222       meaningless.  Locale::Maketext is object-oriented.  You can always
223       raise a new language handle for another text domain.  This is different
224       from the situation of GNU gettext.  Also, the category is always
225       "LC_MESSAGES".  Of course it is.  We are gettext and Maketext.
226
227       Avoid creating different language handles with different textdomain on
228       the same localization subclass.  This currently works, but it violates
229       the basic design of Locale::Maketext(3).  In Locale::Maketext(3),
230       %Lexicon is saved as a class variable, in order for the lexicon
231       inheritance system to work.  So, multiple language handles to a same
232       localization subclass shares a same lexicon space.  Their lexicon space
233       clash.  I tried to avoid this problem by saving a copy of the current
234       lexicon as an instance variable, and replacing the class lexicon with
235       the current instance lexicon whenever it is changed by another language
236       handle instance.  But this involves large scaled memory copy, which
237       affects the proformance seriously.  This is discouraged.  You are
238       adviced to use a single textdomain for a single localization class.
239
240       The "key_encoding" is a workaround, not a solution.  There is no
241       solution to this problem yet.  You should avoid using non-English
242       language as your original text.  You will get yourself into trouble if
243       you mix several original text encodings, for example, joining several
244       pieces of code from programmers all around the world, with their
245       messages written in their own language and encodings.  Solution
246       suggestions are welcome.
247
248       "pgettext" in GNU gettext is implemented as "pmaketext", in order to
249       look up the text message translation in a particular context.  Thanks
250       to the suggestion from Chris Travers.
251

BUGS

253       GNU gettext never fails.  I tries to achieve it as long as possible.
254       The only reason that maketext may die unexpectedly now is "Unterminated
255       bracket group".  I cannot get a better solution to it currently.
256       Suggestions are welcome.
257
258       You are welcome to fix my English.  I have done my best to this
259       documentation, but I am not a native English speaker after all. ^^;
260

SEE ALSO

262       Locale::Maketext(3), Locale::Maketext::TPJ13(3),
263       Locale::Maketext::Lexicon(3), Encode(3), bindtextdomain(3),
264       textdomain(3).  Also, please refer to the official GNU gettext manual
265       at <http://www.gnu.org/software/gettext/manual/>.
266

AUTHOR

268       imacat <imacat@mail.imacat.idv.tw>
269
271       Copyright (c) 2003-2019 imacat. All rights reserved. This program is
272       free software; you can redistribute it and/or modify it under the same
273       terms as Perl itself.
274
275
276
277perl v5.30.1                      2020-01-30      Locale::Maketext::Gettext(3)
Impressum