Locale::Maketext::Gettext::Functions(3pm)

1Locale::Maketext::GetteUxste:r:FCuonncttriiobnust(e3d)PLeorclalDeo:c:uMmaeknettaetxito:n:Gettext::Functions(3)
2
3
4

NAME

6       Locale::Maketext::Gettext::Functions - Functional interface to
7       Locale::Maketext::Gettext
8

SYNOPSIS

10         use Locale::Maketext::Gettext::Functions;
11         bindtextdomain(DOMAIN, LOCALEDIR);
12         textdomain(DOMAIN);
13         get_handle("de");
14         print __("Hello, world!\n");
15

DESCRIPTION

17       Locale::Maketext::Gettext::Functions is a functional interface to
18       Locale::Maketext::Gettext(3) (and Locale::Maketext(3)).  It works
19       exactly the GNU gettext way.  It plays magic to Locale::Maketext(3) for
20       you.  No more localization class/subclasses and language handles are
21       required at all.
22
23       The "maketext", "dmaketext", "pmaketext" and "dpmaketext" functions
24       attempt to translate a text message into the native language of the
25       user, by looking up the translation in an MO lexicon file.
26

FUNCTIONS

28       bindtextdomain(DOMAIN, LOCALEDIR)
29           Register a text domain with a locale directory.  Returns
30           "LOCALEDIR" itself.  If "LOCALEDIR" is omitted, the registered
31           locale directory of "DOMAIN" is returned.  This method always
32           success.
33
34       textdomain(DOMAIN)
35           Set the current text domain.  Returns the "DOMAIN" itself.  if
36           "DOMAIN" is omitted, the current text domain is returned.  This
37           method always success.
38
39       get_handle(@languages)
40           Set the language of the user.  It searches for an available
41           language in the provided @languages list.  If @languages was not
42           provided, it looks checks environment variable LANG, and
43           HTTP_ACCEPT_LANGUAGE when running as CGI.  Refer to
44           Locale::Maketext(3) for the magic of the "get_handle".
45
46       $message = maketext($key, @param...)
47           Attempts to translate a text message into the native language of
48           the user, by looking up the translation in an MO lexicon file.
49           Refer to Locale::Maketext(3) for the "maketext" plural grammer.
50
51       $message = __($key, @param...)
52           A synonym to "maketext()".  This is a shortcut to "maketext()" so
53           that it is cleaner when you employ maketext to your existing
54           project.
55
56       ($key, @param...) = N_($key, @param...)
57           Returns the original text untouched.  This is to enable the text be
58           catched with xgettext.
59
60       $message = dmaketext($domain, $key, @param...)
61           Temporarily switch to another text domain and attempts to translate
62           a text message into the native language of the user in that text
63           domain.  Use "--keyword=dmaketext:2" for the xgettext utility.
64
65       $message = pmaketext($ctxt, $key, @param...)
66           Attempts to translate a text message in a particular context into
67           the native language of the user.  Use "--keyword=pmaketext:1c,2"
68           for the xgettext utility.
69
70       $message = dpmaketext($domain, $ctxt, $key, @param...)
71           Temporarily switch to another text domain and attempts to translate
72           a text message in a particular context into the native language of
73           the user in that text domain.  Use "--keyword=dpmaketext:2c,3" for
74           the xgettext utility.
75
76       encoding(ENCODING)
77           Set or retrieve the output encoding.  The default is the same
78           encoding as the gettext MO file.  You can specify "undef", to
79           return the result in unencoded UTF-8.
80
81       key_encoding(ENCODING)
82           Specify the encoding used in your original text.  The "maketext"
83           method itself is not multibyte-safe to the _AUTO lexicon.  If you
84           are using your native non-English language as your original text
85           and you are having troubles like:
86
87           Unterminated bracket group, in:
88
89           Then, specify the "key_encoding" to the encoding of your original
90           text.  Returns the current setting.
91
92           WARNING: You should always use US-ASCII text keys.  Using non-US-
93           ASCII keys is always discouraged and is not guaranteed to be
94           working.
95
96       encode_failure(CHECK)
97           Set the action when encode fails.  This happens when the output
98           text is out of the scope of your output encoding.  For exmaple,
99           output Chinese into US-ASCII.  Refer to Encode(3) for the possible
100           values of this "CHECK".  The default is "FB_DEFAULT", which is a
101           safe choice that never fails.  But part of your text may be lost,
102           since that is what "FB_DEFAULT" does.  Returns the current setting.
103
104       die_for_lookup_failures(SHOULD_I_DIE)
105           Maketext dies for lookup failures, but GNU gettext never fails.  By
106           default Lexicon::Maketext::Gettext follows the GNU gettext
107           behavior.  But if you are Maketext-styled, or if you need a better
108           control over the failures (like me :p), set this to 1.  Returns the
109           current setting.
110
111       reload_text()
112           Purges the MO text cache.  By default MO files are cached after
113           they are read and parsed from the disk, to reduce I/O and parsing
114           overhead on busy sites.  reload_text() purges this cache, so that
115           updated MO files can take effect at run-time.  This is used when
116           your MO file is updated, but you cannot shutdown and restart the
117           application.  for example, when you are a co-hoster on a
118           mod_perl-enabled Apache, or when your mod_perl-enabled Apache is
119           too vital to be restarted for every update of your MO file, or if
120           you are running a vital daemon, such as an X display server.
121
122       %Lexicon = read_mo($MOfile)
123           Read and parse the MO file.  Returns the read %Lexicon.  The
124           returned lexicon is in its original encoding.
125
126           If you need the meta infomation of your MO file, parse the entry
127           $Lexicon{""}.  For example:
128
129             /^Content-Type: text\/plain; charset=(.*)$/im;
130             $encoding = $1;
131

NOTES

133       NOTE: Since localization classes are generated at run-time, it is not
134       possible to override the Maketext language functions, like "quant" or
135       "numerate".  If that is your concern, use Locale::Maketext::Gettext(3)
136       instead.  Suggestions are welcome.
137
138       You can now add/remove languages/MO files at run-time.  This is a major
139       improvement over the original Locale::Maketext::Gettext(3) (and
140       Locale::Maketext(3)).  This is done by registering localization classes
141       with random IDs, so that the same text domain can be re-declared
142       infinitely, whenever needed (language list changes, LOCALEDIR changes,
143       etc.)  This is not possible to the object-interface of
144       Locale::Maketext::Gettext(3) (and Locale::Maketext(3)).
145
146       Language addition/removal takes effect only after "bindtextdomain" or
147       "textdomain" is called.  It has no effect on "maketext" calls.  This
148       keeps a basic sanity in the lifetime of a running script.
149
150       If you set "textdomain" to a domain that is not "bindtextdomain" to
151       specific a locale directory yet, it will try search system locale
152       directories.  The current system locale directory search order is:
153       /usr/share/locale, /usr/lib/locale, /usr/local/share/locale,
154       /usr/local/lib/locale.  Suggestions are welcome.
155

STORY

157       The idea is that:  I finally realized that, no matter how hard I try, I
158       can never get a never-failure "maketext".  A common wrapper like:
159
160         sub __ { return $LH->maketext(@_) };
161
162       always fails if $LH is not initialized yet.  For this reason,
163       "maketext" can hardly be employed in error handlers to output graceful
164       error messages in the natural language of the user.  So, I have to
165       write something like this:
166
167         sub __ {
168             $LH = MyPkg::L10N->get_handle if !defined $LH;
169             return $LH->maketext(@_);
170         }
171
172       But what if "get_handle" itself fails?  So, this becomes:
173
174         sub __ {
175             $LH = MyPkg::L10N->get_handle if !defined $LH;
176             $LH = _AUTO->get_handle if !defined $LH;
177             return $LH->maketext(@_);
178         }
179         package _AUTO;
180         use base qw(Locale::Maketext);
181         package _AUTO::i_default;
182         use base qw(Locale::Maketext);
183         %Lexicon = ( "_AUTO" => 1 );
184
185       Ya, this works.  But, if I always have to do this in my every
186       application, why should I not make a solution to the localization
187       framework itself?  This is a common problem to every localization
188       projects.  It should be solved at the localization framework level, but
189       not at the application level.
190
191       Another reason is that:  Programmers should be able to use "maketext"
192       without the knowledge of object-oriented programming.  A localization
193       framework should be neat and simple.  It should lower down its barrier,
194       be friendly to the beginners, in order to encourage the use of
195       localization and globalization.  Apparently the current practice of
196       Locale::Maketext(3) does not satisfy this request.
197
198       The third reason is:  Since Locale::Maketext::Gettext(3) imports the
199       lexicon from foreign sources, the class source file is left empty.  It
200       exists only to help the "get_handle" method looking for a proper
201       language handle.  Then, why not make it disappear, and be generated
202       whenever needed?  Why bother the programmers to put an empty class
203       source file there?
204
205       How neat can we be?
206
207       imacat, 2003-04-29
208

BUGS

210       Since maketext localization classes are generated at run time, Maketext
211       language function override, like "quant" or "numerate", is not
212       available here.  Suggestions are welcome.
213
214       "encoding", "key_encoding", "encode_failure" and
215       "die_for_lookup_failures" are not mod_perl-safe.  These settings affect
216       the whole process, including the following scripts it is going to run.
217       This is the same as "setlocale" in POSIX(3).  Always set them at the
218       very beginning of your script if you are running under mod_perl.  If
219       you do not like it, use the object-oriented
220       Locale::Maketext::Gettext(3) instead.  Suggestions are welcome.
221
222       Smart translation between Traditional Chinese/Simplified Chinese, like
223       what GNU gettext does, is not available yet.  Suggestions are welcome.
224

AUTHOR

232       imacat <imacat@mail.imacat.idv.tw>
233

COPYRIGHT

235       Copyright (c) 2003-2008 imacat. All rights reserved. This program is
236       free software; you can redistribute it and/or modify it under the same
237       terms as Perl itself.
238
239
240
241perl v5.10.1                      2010-1L1o-c1a2le::Maketext::Gettext::Functions(3)