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

NOTES

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

STORY

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

BUGS

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

AUTHOR

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

COPYRIGHT

234       Copyright (c) 2003-2021 imacat. All rights reserved. This program is
235       free software; you can redistribute it and/or modify it under the same
236       terms as Perl itself.
237
238
239
240perl v5.36.0                      2023-0L1o-c2a0le::Maketext::Gettext::Functions(3)