1Locale::Maketext::GetteUxste(r3)Contributed Perl DocumenLtoactailoen::Maketext::Gettext(3)
2
6 Locale::Maketext::Gettext - Joins the gettext and Maketext frameworks
7
9 In your localization class:
10 package MyPackage::L10N;
12 use base qw(Locale::Maketext::Gettext);
13 return 1;
14 In your application:
16 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 If you want to have more control to the detail:
24 # 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 Use Locale::Maketext::Gettext to read and parse the MO file:
37 use Locale::Maketext::Gettext;
39 %Lexicon = read_mo($mo_file);
40
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 You start as a 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 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
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 $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 $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 $text = $LH->pmaketext($context, $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 $LH->language_tag
82 Retrieve the language tag. This is the same method in
83 Locale::Maketext(3). It is readonly.
84 $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 $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 Unterminated bracket group, in:
97 Then, specify the "key_encoding" to the encoding of your original
99 text. Returns the current setting.
100 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 $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 example,
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 $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 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 $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 virtual
131 host on a mod_perl-enabled Apache, or when your mod_perl-enabled
132 Apache is too vital to be restarted for every update of your MO
133 file, or if you are running a vital daemon, such as an X display
134 server.
135
137 %Lexicon = read_mo($mo_file);
138 Read and parse the MO file. Returns the read %Lexicon. The
139 returned lexicon is in its original encoding.
140 If you need the meta information of your MO file, parse the entry
142 $Lexicon{""}. For example:
143 /^Content-Type: text\/plain; charset=(.*)$/im;
145 $encoding = $1;
146 "read_mo()" is exported by default, but you need to "use
148 Locale::Maketext::Gettext" in order to use it. It is not exported
149 from your localization class, but from the
150 Locale::Maketext::Gettext package.
151
153 WARNING: do not try to put any lexicon in your language subclass. When
154 the "textdomain" method is called, the current lexicon will be
155 replaced, but not appended. This is to accommodate the way
156 "textdomain" works. Messages from the previous text domain should not
157 stay in the current text domain.
158 An essential benefit of this Locale::Maketext::Gettext over the
160 original Locale::Maketext(3) is that: GNU gettext is multibyte safe,
161 but Perl source is not. GNU gettext is safe to Big5 characters like
162 \xa5\x5c (Gong1). But if you follow the current Locale::Maketext(3)
163 document and put your lexicon as a hash in the source of a localization
164 subclass, you have to escape bytes like \x5c, \x40, \x5b, etc., in the
165 middle of some natural multibyte characters. This breaks these
166 characters in halves. Your non-technical translators and reviewers
167 will be presented with unreadable mess, "Luan4Ma3". Sorry to say this,
168 but it is weird for a localization framework to be not multibyte-safe.
169 But, well, here comes Locale::Maketext::Gettext to rescue. With
170 Locale::Maketext::Gettext, you can sit back and relax now, leaving all
171 this mess to the excellent GNU gettext framework.
172 The idea of Locale::Maketext::Gettext came from
174 Locale::Maketext::Lexicon(3), a great work by Autrijus. But it has
175 several problems at that time (version 0.16). I was first trying to
176 write a wrapper to fix it, but finally I dropped it and decided to make
177 a solution towards Locale::Maketext(3) itself.
178 Locale::Maketext::Lexicon(3) should be fine now if you obtain a version
179 newer than 0.16.
180 Locale::Maketext::Gettext also solved the problem of lack of the
182 ability to handle the encoding in Locale::Maketext(3). I implement
183 this since this is what GNU gettext does. When %Lexicon is read from
184 MO files by "read_mo()", the encoding tagged in gettext MO files is
185 used to "decode" the text into the internal encoding of Perl. Then,
186 when extracted by "maketext", it is "encode"d by the current "encoding"
187 value. The "encoding" can be set at run time, so that you can run a
188 daemon and output to different encoding according to the language
189 settings of individual users, without having to restart the
190 application. This is an improvement to the Locale::Maketext(3), and is
191 essential to daemons and "mod_perl" applications.
192 You should trust the encoding of your gettext MO file. GNU gettext
194 "msgfmt" checks the illegal characters for you when you compile your MO
195 file from your PO file. The encoding form your MO files are always
196 good. If you try to output to a wrong encoding, part of your text may
197 be lost, as "FB_DEFAULT" does. If you do not like this "FB_DEFAULT",
198 change the failure behavior with the method "encode_failure".
199 If you need the behavior of auto Traditional Chinese/Simplified Chinese
201 conversion, as GNU gettext smartly does, do it yourself with
202 Encode::HanExtra(3), too. There may be a solution for this in the
203 future, but not now.
204 If you set "textdomain" to a domain that is not "bindtextdomain" to
206 specific a locale directory yet, it will try search system locale
207 directories. The current system locale directory search order is:
208 /usr/share/locale, /usr/lib/locale, /usr/local/share/locale,
209 /usr/local/lib/locale. Suggestions for this search order are welcome.
210 NOTICE: MyPackage::L10N::en->maketext(...) is not available anymore, as
212 the "maketext" method is no more static. That is a sure result, as
213 %Lexicon is imported from foreign sources dynamically, but not
214 statically hardcoded in Perl sources. But the documentation of
215 Locale::Maketext(3) does not say that you can use it as a static method
216 anyway. Maybe you were practicing this before. You had better check
217 your existing code for this. If you try to invoke it statically, it
218 returns "undef".
219 "dgettext" and "dcgettext" in GNU gettext are not implemented. It is
221 not possible to temporarily change the current text domain in the
222 current design of Locale::Maketext::Gettext. Besides, it is
223 meaningless. Locale::Maketext is object-oriented. You can always
224 raise a new language handle for another text domain. This is different
225 from the situation of GNU gettext. Also, the category is always
226 "LC_MESSAGES". Of course it is. We are gettext and Maketext.
227 Avoid creating different language handles with different textdomain on
229 the same localization subclass. This currently works, but it violates
230 the basic design of Locale::Maketext(3). In Locale::Maketext(3),
231 %Lexicon is saved as a class variable, in order for the lexicon
232 inheritance system to work. So, multiple language handles to a same
233 localization subclass shares a same lexicon space. Their lexicon space
234 clash. I tried to avoid this problem by saving a copy of the current
235 lexicon as an instance variable, and replacing the class lexicon with
236 the current instance lexicon whenever it is changed by another language
237 handle instance. But this involves large scaled memory copy, which
238 affects the performance seriously. This is discouraged. You are
239 advised to use a single textdomain for a single localization class.
240 The "key_encoding" is a workaround, not a solution. There is no
242 solution to this problem yet. You should avoid using non-English
243 language as your original text. You will get yourself into trouble if
244 you mix several original text encodings, for example, joining several
245 pieces of code from programmers all around the world, with their
246 messages written in their own language and encodings. Solution
247 suggestions are welcome.
248 "pgettext" in GNU gettext is implemented as "pmaketext", in order to
250 look up the text message translation in a particular context. Thanks
251 to the suggestion from Chris Travers.
252
254 GNU gettext never fails. I tries to achieve it as long as possible.
255 The only reason that maketext may die unexpectedly now is "Unterminated
256 bracket group". I cannot get a better solution to it currently.
257 Suggestions are welcome.
258 You are welcome to fix my English. I have done my best to this
260 documentation, but I am not a native English speaker after all. ^^;
261
263 Locale::Maketext(3), Locale::Maketext::TPJ13(3),
264 Locale::Maketext::Lexicon(3), Encode(3), bindtextdomain(3),
265 textdomain(3). Also, please refer to the official GNU gettext manual
266 at <https://www.gnu.org/software/gettext/manual/>.
267
269 imacat <imacat@mail.imacat.idv.tw>
270
272 Copyright (c) 2003-2021 imacat. All rights reserved. This program is
273 free software; you can redistribute it and/or modify it under the same
274 terms as Perl itself.
275perl v5.34.0 2021-07-22 Locale::Maketext::Gettext(3)