Debian Codegraph @

upstream/debian-unstable/man3/Locale::Maketext.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Locale::Maketext 3perl"
58 .TH Locale::Maketext 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Locale::Maketext \- framework for localization
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 9
68 \& package MyProgram;
69 \& use strict;
70 \& use MyProgram::L10N;
71 \& # ...which inherits from Locale::Maketext
72 \& my $lh = MyProgram::L10N\->get_handle() || die "What language?";
73 \& ...
74 \& # And then any messages your program emits, like:
75 \& warn $lh\->maketext( "Can\*(Aqt open file [_1]: [_2]\en", $f, $! );
76 \& ...
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 It is a common feature of applications (whether run directly,
81 or via the Web) for them to be "localized" \-\- i.e., for them
82 to a present an English interface to an English-speaker, a German
83 interface to a German-speaker, and so on for all languages it's
84 programmed with. Locale::Maketext
85 is a framework for software localization; it provides you with the
86 tools for organizing and accessing the bits of text and text-processing
87 code that you need for producing localized applications.
88 .PP
89 In order to make sense of Maketext and how all its
90 components fit together, you should probably
91 go read Locale::Maketext::TPJ13, and
92 \&\fIthen\fR read the following documentation.
93 .PP
94 You may also want to read over the source for \f(CW\*(C`File::Findgrep\*(C'\fR
95 and its constituent modules \-\- they are a complete (if small)
96 example application that uses Maketext.
97 .SH "QUICK OVERVIEW"
98 .IX Header "QUICK OVERVIEW"
99 The basic design of Locale::Maketext is object-oriented, and
100 Locale::Maketext is an abstract base class, from which you
101 derive a "project class".
102 The project class (with a name like "TkBocciBall::Localize",
103 which you then use in your module) is in turn the base class
104 for all the "language classes" for your project
105 (with names "TkBocciBall::Localize::it",
106 "TkBocciBall::Localize::en",
107 "TkBocciBall::Localize::fr", etc.).
108 .PP
109 A language class is
110 a class containing a lexicon of phrases as class data,
111 and possibly also some methods that are of use in interpreting
112 phrases in the lexicon, or otherwise dealing with text in that
113 language.
114 .PP
115 An object belonging to a language class is called a "language
116 handle"; it's typically a flyweight object.
117 .PP
118 The normal course of action is to call:
119 .PP
120 .Vb 6
121 \& use TkBocciBall::Localize; # the localization project class
122 \& $lh = TkBocciBall::Localize\->get_handle();
123 \& # Depending on the user\*(Aqs locale, etc., this will
124 \& # make a language handle from among the classes available,
125 \& # and any defaults that you declare.
126 \& die "Couldn\*(Aqt make a language handle??" unless $lh;
127 .Ve
128 .PP
129 From then on, you use the \f(CW\*(C`maketext\*(C'\fR function to access
130 entries in whatever lexicon(s) belong to the language handle
131 you got. So, this:
132 .PP
133 .Vb 1
134 \& print $lh\->maketext("You won!"), "\en";
135 .Ve
136 .PP
137 \&...emits the right text for this language. If the object
138 in \f(CW$lh\fR belongs to class "TkBocciBall::Localize::fr" and
139 \&\f(CW%TkBocciBall::Localize::fr::Lexicon\fR contains \f(CW\*(C`("You won!"
140 => "Tu as gagné!")\*(C'\fR, then the above
141 code happily tells the user "Tu as gagné!".
142 .SH METHODS
143 .IX Header "METHODS"
144 Locale::Maketext offers a variety of methods, which fall
145 into three categories:
146 .IP \(bu 4
147 Methods to do with constructing language handles.
148 .IP \(bu 4
149 \&\f(CW\*(C`maketext\*(C'\fR and other methods to do with accessing \f(CW%Lexicon\fR data
150 for a given language handle.
151 .IP \(bu 4
152 Methods that you may find it handy to use, from routines of
153 yours that you put in \f(CW%Lexicon\fR entries.
154 .PP
155 These are covered in the following section.
156 .SS "Construction Methods"
157 .IX Subsection "Construction Methods"
158 These are to do with constructing a language handle:
159 .IP \(bu 4
160 \&\f(CW$lh\fR = YourProjClass\->get_handle( ...langtags... ) || die "lg-handle?";
161 .Sp
162 This tries loading classes based on the language-tags you give (like
163 \&\f(CW\*(C`("en\-US", "sk", "kon", "es\-MX", "ja", "i\-klingon")\*(C'\fR, and for the first class
164 that succeeds, returns YourProjClass::\fIlanguage\fR\->\fBnew()\fR.
165 .Sp
166 If it runs thru the entire given list of language-tags, and finds no classes
167 for those exact terms, it then tries "superordinate" language classes.
168 So if no "en-US" class (i.e., YourProjClass::en_us)
169 was found, nor classes for anything else in that list, we then try
170 its superordinate, "en" (i.e., YourProjClass::en), and so on thru
171 the other language-tags in the given list: "es".
172 (The other language-tags in our example list:
173 happen to have no superordinates.)
174 .Sp
175 If none of those language-tags leads to loadable classes, we then
176 try classes derived from YourProjClass\->\fBfallback_languages()\fR and
177 then if nothing comes of that, we use classes named by
178 YourProjClass\->\fBfallback_language_classes()\fR. Then in the (probably
179 quite unlikely) event that that fails, we just return undef.
180 .IP \(bu 4
181 \&\f(CW$lh\fR = YourProjClass\->get_handle\fB()\fR || die "lg-handle?";
182 .Sp
183 When \f(CW\*(C`get_handle\*(C'\fR is called with an empty parameter list, magic happens:
184 .Sp
185 If \f(CW\*(C`get_handle\*(C'\fR senses that it's running in program that was
186 invoked as a CGI, then it tries to get language-tags out of the
187 environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that
188 those were the languages passed as parameters to \f(CW\*(C`get_handle\*(C'\fR.
189 .Sp
190 Otherwise (i.e., if not a CGI), this tries various OS-specific ways
191 to get the language-tags for the current locale/language, and then
192 pretends that those were the value(s) passed to \f(CW\*(C`get_handle\*(C'\fR.
193 .Sp
194 Currently this OS-specific stuff consists of looking in the environment
195 variables "LANG" and "LANGUAGE"; and on MSWin machines (where those
196 variables are typically unused), this also tries using
197 the module Win32::Locale to get a language-tag for whatever language/locale
198 is currently selected in the "Regional Settings" (or "International"?)
199 Control Panel. I welcome further
200 suggestions for making this do the Right Thing under other operating
201 systems that support localization.
202 .Sp
203 If you're using localization in an application that keeps a configuration
204 file, you might consider something like this in your project class:
205 .Sp
206 .Vb 10
207 \& sub get_handle_via_config {
208 \& my $class = $_[0];
209 \& my $chosen_language = $Config_settings{\*(Aqlanguage\*(Aq};
210 \& my $lh;
211 \& if($chosen_language) {
212 \& $lh = $class\->get_handle($chosen_language)
213 \& || die "No language handle for \e"$chosen_language\e""
214 \& . " or the like";
215 \& } else {
216 \& # Config file missing, maybe?
217 \& $lh = $class\->get_handle()
218 \& || die "Can\*(Aqt get a language handle";
219 \& }
220 \& return $lh;
221 \& }
222 .Ve
223 .IP \(bu 4
224 \&\f(CW$lh\fR = YourProjClass::langname\->\fBnew()\fR;
225 .Sp
226 This constructs a language handle. You usually \fBdon't\fR call this
227 directly, but instead let \f(CW\*(C`get_handle\*(C'\fR find a language class to \f(CW\*(C`use\*(C'\fR
228 and to then call \->new on.
229 .IP \(bu 4
230 \&\f(CW$lh\fR\->\fBinit()\fR;
231 .Sp
232 This is called by \->new to initialize newly-constructed language handles.
233 If you define an init method in your class, remember that it's usually
234 considered a good idea to call \f(CW$lh\fR\->SUPER::init in it (presumably at the
235 beginning), so that all classes get a chance to initialize a new object
236 however they see fit.
237 .IP \(bu 4
238 YourProjClass\->\fBfallback_languages()\fR
239 .Sp
240 \&\f(CW\*(C`get_handle\*(C'\fR appends the return value of this to the end of
241 whatever list of languages you pass \f(CW\*(C`get_handle\*(C'\fR. Unless
242 you override this method, your project class
243 will inherit Locale::Maketext's \f(CW\*(C`fallback_languages\*(C'\fR, which
244 currently returns \f(CW\*(C`(\*(Aqi\-default\*(Aq, \*(Aqen\*(Aq, \*(Aqen\-US\*(Aq)\*(C'\fR.
245 ("i\-default" is defined in RFC 2277).
246 .Sp
247 This method (by having it return the name
248 of a language-tag that has an existing language class)
249 can be used for making sure that
250 \&\f(CW\*(C`get_handle\*(C'\fR will always manage to construct a language
251 handle (assuming your language classes are in an appropriate
252 \&\f(CW@INC\fR directory). Or you can use the next method:
253 .IP \(bu 4
254 YourProjClass\->\fBfallback_language_classes()\fR
255 .Sp
256 \&\f(CW\*(C`get_handle\*(C'\fR appends the return value of this to the end
257 of the list of classes it will try using. Unless
258 you override this method, your project class
259 will inherit Locale::Maketext's \f(CW\*(C`fallback_language_classes\*(C'\fR,
260 which currently returns an empty list, \f(CW\*(C`()\*(C'\fR.
261 By setting this to some value (namely, the name of a loadable
262 language class), you can be sure that
263 \&\f(CW\*(C`get_handle\*(C'\fR will always manage to construct a language
264 handle.
265 .SS "The ""maketext"" Method"
266 .IX Subsection "The ""maketext"" Method"
267 This is the most important method in Locale::Maketext:
268 .PP
269 .Vb 1
270 \& $text = $lh\->maketext(I<key>, ...parameters for this phrase...);
271 .Ve
272 .PP
273 This looks in the \f(CW%Lexicon\fR of the language handle
274 \&\f(CW$lh\fR and all its superclasses, looking
275 for an entry whose key is the string \fIkey\fR. Assuming such
276 an entry is found, various things then happen, depending on the
277 value found:
278 .PP
279 If the value is a scalarref, the scalar is dereferenced and returned
280 (and any parameters are ignored).
281 .PP
282 If the value is a coderef, we return &$value($lh, ...parameters...).
283 .PP
284 If the value is a string that \fIdoesn't\fR look like it's in Bracket Notation,
285 we return it (after replacing it with a scalarref, in its \f(CW%Lexicon\fR).
286 .PP
287 If the value \fIdoes\fR look like it's in Bracket Notation, then we compile
288 it into a sub, replace the string in the \f(CW%Lexicon\fR with the new coderef,
289 and then we return &$new_sub($lh, ...parameters...).
290 .PP
291 Bracket Notation is discussed in a later section. Note
292 that trying to compile a string into Bracket Notation can throw
293 an exception if the string is not syntactically valid (say, by not
294 balancing brackets right.)
295 .PP
296 Also, calling &$coderef($lh, ...parameters...) can throw any sort of
297 exception (if, say, code in that sub tries to divide by zero). But
298 a very common exception occurs when you have Bracket
299 Notation text that says to call a method "foo", but there is no such
300 method. (E.g., "You have [qua\fBtn\fR,_1,ball]." will throw an exception
301 on trying to call \f(CW$lh\fR\->qua\fBtn\fR($_[1],'ball') \-\- you presumably meant
302 "quant".) \f(CW\*(C`maketext\*(C'\fR catches these exceptions, but only to make the
303 error message more readable, at which point it rethrows the exception.
304 .PP
305 An exception \fImay\fR be thrown if \fIkey\fR is not found in any
306 of \f(CW$lh\fR's \f(CW%Lexicon\fR hashes. What happens if a key is not found,
307 is discussed in a later section, "Controlling Lookup Failure".
308 .PP
309 Note that you might find it useful in some cases to override
310 the \f(CW\*(C`maketext\*(C'\fR method with an "after method", if you want to
311 translate encodings, or even scripts:
312 .PP
313 .Vb 7
314 \& package YrProj::zh_cn; # Chinese with PRC\-style glyphs
315 \& use base (\*(AqYrProj::zh_tw\*(Aq); # Taiwan\-style
316 \& sub maketext {
317 \& my $self = shift(@_);
318 \& my $value = $self\->maketext(@_);
319 \& return Chineeze::taiwan2mainland($value);
320 \& }
321 .Ve
322 .PP
323 Or you may want to override it with something that traps
324 any exceptions, if that's critical to your program:
325 .PP
326 .Vb 7
327 \& sub maketext {
328 \& my($lh, @stuff) = @_;
329 \& my $out;
330 \& eval { $out = $lh\->SUPER::maketext(@stuff) };
331 \& return $out unless $@;
332 \& ...otherwise deal with the exception...
333 \& }
334 .Ve
335 .PP
336 Other than those two situations, I don't imagine that
337 it's useful to override the \f(CW\*(C`maketext\*(C'\fR method. (If
338 you run into a situation where it is useful, I'd be
339 interested in hearing about it.)
340 .ie n .IP "$lh\->fail_with \fIor\fR $lh\->fail_with(\fIPARAM\fR)" 4
341 .el .IP "\f(CW$lh\fR\->fail_with \fIor\fR \f(CW$lh\fR\->fail_with(\fIPARAM\fR)" 4
342 .IX Item "$lh->fail_with or $lh->fail_with(PARAM)"
343 .PD 0
344 .ie n .IP $lh\->failure_handler_auto 4
345 .el .IP \f(CW$lh\fR\->failure_handler_auto 4
346 .IX Item "$lh->failure_handler_auto"
347 .PD
348 These two methods are discussed in the section "Controlling
349 Lookup Failure".
350 .ie n .IP "$lh\->denylist(@list) <or> $lh\->blacklist(@list)" 4
351 .el .IP "\f(CW$lh\fR\->denylist(@list) <or> \f(CW$lh\fR\->blacklist(@list)" 4
352 .IX Item "$lh->denylist(@list) <or> $lh->blacklist(@list)"
353 .PD 0
354 .ie n .IP "$lh\->allowlist(@list) <or> $lh\->whitelist(@list)" 4
355 .el .IP "\f(CW$lh\fR\->allowlist(@list) <or> \f(CW$lh\fR\->whitelist(@list)" 4
356 .IX Item "$lh->allowlist(@list) <or> $lh->whitelist(@list)"
357 .PD
358 These methods are discussed in the section "Bracket Notation
359 Security".
360 .SS "Utility Methods"
361 .IX Subsection "Utility Methods"
362 These are methods that you may find it handy to use, generally
363 from \f(CW%Lexicon\fR routines of yours (whether expressed as
364 Bracket Notation or not).
365 .ie n .IP "$language\->quant($number, $singular)" 4
366 .el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR)" 4
367 .IX Item "$language->quant($number, $singular)"
368 .PD 0
369 .ie n .IP "$language\->quant($number, $singular, $plural)" 4
370 .el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR)" 4
371 .IX Item "$language->quant($number, $singular, $plural)"
372 .ie n .IP "$language\->quant($number, $singular, $plural, $negative)" 4
373 .el .IP "\f(CW$language\fR\->quant($number, \f(CW$singular\fR, \f(CW$plural\fR, \f(CW$negative\fR)" 4
374 .IX Item "$language->quant($number, $singular, $plural, $negative)"
375 .PD
376 This is generally meant to be called from inside Bracket Notation
377 (which is discussed later), as in
378 .Sp
379 .Vb 1
380 \& "Your search matched [quant,_1,document]!"
381 .Ve
382 .Sp
383 It's for \fIquantifying\fR a noun (i.e., saying how much of it there is,
384 while giving the correct form of it). The behavior of this method is
385 handy for English and a few other Western European languages, and you
386 should override it for languages where it's not suitable. You can feel
387 free to read the source, but the current implementation is basically
388 as this pseudocode describes:
389 .Sp
390 .Vb 11
391 \& if $number is 0 and there\*(Aqs a $negative,
392 \& return $negative;
393 \& elsif $number is 1,
394 \& return "1 $singular";
395 \& elsif there\*(Aqs a $plural,
396 \& return "$number $plural";
397 \& else
398 \& return "$number " . $singular . "s";
399 \& #
400 \& # ...except that we actually call numf to
401 \& # stringify $number before returning it.
402 .Ve
403 .Sp
404 So for English (with Bracket Notation)
405 \&\f(CW"...[quant,_1,file]..."\fR is fine (for 0 it returns "0 files",
406 for 1 it returns "1 file", and for more it returns "2 files", etc.)
407 .Sp
408 But for "directory", you'd want \f(CW"[quant,_1,directory,directories]"\fR
409 so that our elementary \f(CW\*(C`quant\*(C'\fR method doesn't think that the
410 plural of "directory" is "directorys". And you might find that the
411 output may sound better if you specify a negative form, as in:
412 .Sp
413 .Vb 1
414 \& "[quant,_1,file,files,No files] matched your query.\en"
415 .Ve
416 .Sp
417 Remember to keep in mind verb agreement (or adjectives too, in
418 other languages), as in:
419 .Sp
420 .Vb 1
421 \& "[quant,_1,document] were matched.\en"
422 .Ve
423 .Sp
424 Because if _1 is one, you get "1 document \fBwere\fR matched".
425 An acceptable hack here is to do something like this:
426 .Sp
427 .Vb 1
428 \& "[quant,_1,document was, documents were] matched.\en"
429 .Ve
430 .ie n .IP $language\->numf($number) 4
431 .el .IP \f(CW$language\fR\->numf($number) 4
432 .IX Item "$language->numf($number)"
433 This returns the given number formatted nicely according to
434 this language's conventions. Maketext's default method is
435 mostly to just take the normal string form of the number
436 (applying sprintf "%G" for only very large numbers), and then
437 to add commas as necessary. (Except that
438 we apply \f(CW\*(C`tr/,./.,/\*(C'\fR if \f(CW$language\fR\->{'numf_comma'} is true;
439 that's a bit of a hack that's useful for languages that express
440 two million as "2.000.000" and not as "2,000,000").
441 .Sp
442 If you want anything fancier, consider overriding this with something
443 that uses Number::Format, or does something else
444 entirely.
445 .Sp
446 Note that numf is called by quant for stringifying all quantifying
447 numbers.
448 .ie n .IP "$language\->numerate($number, $singular, $plural, $negative)" 4
449 .el .IP "\f(CW$language\fR\->numerate($number, \f(CW$singular\fR, \f(CW$plural\fR, \f(CW$negative\fR)" 4
450 .IX Item "$language->numerate($number, $singular, $plural, $negative)"
451 This returns the given noun form which is appropriate for the quantity
452 \&\f(CW$number\fR according to this language's conventions. \f(CW\*(C`numerate\*(C'\fR is
453 used internally by \f(CW\*(C`quant\*(C'\fR to quantify nouns. Use it directly \-\-
454 usually from bracket notation \-\- to avoid \f(CW\*(C`quant\*(C'\fR's implicit call to
455 \&\f(CW\*(C`numf\*(C'\fR and output of a numeric quantity.
456 .ie n .IP "$language\->sprintf($format, @items)" 4
457 .el .IP "\f(CW$language\fR\->sprintf($format, \f(CW@items\fR)" 4
458 .IX Item "$language->sprintf($format, @items)"
459 This is just a wrapper around Perl's normal \f(CW\*(C`sprintf\*(C'\fR function.
460 It's provided so that you can use "sprintf" in Bracket Notation:
461 .Sp
462 .Vb 1
463 \& "Couldn\*(Aqt access datanode [sprintf,%10x=~[%s~],_1,_2]!\en"
464 .Ve
465 .Sp
466 returning...
467 .Sp
468 .Vb 1
469 \& Couldn\*(Aqt access datanode Stuff=[thangamabob]!
470 .Ve
471 .ie n .IP $language\->\fBlanguage_tag()\fR 4
472 .el .IP \f(CW$language\fR\->\fBlanguage_tag()\fR 4
473 .IX Item "$language->language_tag()"
474 Currently this just takes the last bit of \f(CWref($language)\fR, turns
475 underscores to dashes, and returns it. So if \f(CW$language\fR is
476 an object of class Hee::HOO::Haw::en_us, \f(CW$language\fR\->\fBlanguage_tag()\fR
477 returns "en-us". (Yes, the usual representation for that language
478 tag is "en-US", but case is \fInever\fR considered meaningful in
479 language-tag comparison.)
480 .Sp
481 You may override this as you like; Maketext doesn't use it for
482 anything.
483 .ie n .IP $language\->\fBencoding()\fR 4
484 .el .IP \f(CW$language\fR\->\fBencoding()\fR 4
485 .IX Item "$language->encoding()"
486 Currently this isn't used for anything, but it's provided
487 (with default value of
488 \&\f(CW\*(C`(ref($language) && $language\->{\*(Aqencoding\*(Aq})) or "iso\-8859\-1"\*(C'\fR
489 ) as a sort of suggestion that it may be useful/necessary to
490 associate encodings with your language handles (whether on a
491 per-class or even per-handle basis.)
492 .SS "Language Handle Attributes and Internals"
493 .IX Subsection "Language Handle Attributes and Internals"
494 A language handle is a flyweight object \-\- i.e., it doesn't (necessarily)
495 carry any data of interest, other than just being a member of
496 whatever class it belongs to.
497 .PP
498 A language handle is implemented as a blessed hash. Subclasses of yours
499 can store whatever data you want in the hash. Currently the only hash
500 entry used by any crucial Maketext method is "fail", so feel free to
501 use anything else as you like.
502 .PP
503 \&\fBRemember: Don't be afraid to read the Maketext source if there's
504 any point on which this documentation is unclear.\fR This documentation
505 is vastly longer than the module source itself.
506 .SH "LANGUAGE CLASS HIERARCHIES"
507 .IX Header "LANGUAGE CLASS HIERARCHIES"
508 These are Locale::Maketext's assumptions about the class
509 hierarchy formed by all your language classes:
510 .IP \(bu 4
511 You must have a project base class, which you load, and
512 which you then use as the first argument in
513 the call to YourProjClass\->get_handle(...). It should derive
514 (whether directly or indirectly) from Locale::Maketext.
515 It \fBdoesn't matter\fR how you name this class, although assuming this
516 is the localization component of your Super Mega Program,
517 good names for your project class might be
518 SuperMegaProgram::Localization, SuperMegaProgram::L10N,
519 SuperMegaProgram::I18N, SuperMegaProgram::International,
520 or even SuperMegaProgram::Languages or SuperMegaProgram::Messages.
521 .IP \(bu 4
522 Language classes are what YourProjClass\->get_handle will try to load.
523 It will look for them by taking each language-tag (\fBskipping\fR it
524 if it doesn't look like a language-tag or locale-tag!), turning it to
525 all lowercase, turning dashes to underscores, and appending it
526 to YourProjClass . "::". So this:
527 .Sp
528 .Vb 3
529 \& $lh = YourProjClass\->get_handle(
530 \& \*(Aqen\-US\*(Aq, \*(Aqfr\*(Aq, \*(Aqkon\*(Aq, \*(Aqi\-klingon\*(Aq, \*(Aqi\-klingon\-romanized\*(Aq
531 \& );
532 .Ve
533 .Sp
534 will try loading the classes
535 YourProjClass::en_us (note lowercase!), YourProjClass::fr,
536 YourProjClass::kon,
537 YourProjClass::i_klingon
538 and YourProjClass::i_klingon_romanized. (And it'll stop at the
539 first one that actually loads.)
540 .IP \(bu 4
541 I assume that each language class derives (directly or indirectly)
542 from your project class, and also defines its \f(CW@ISA\fR, its \f(CW%Lexicon\fR,
543 or both. But I anticipate no dire consequences if these assumptions
544 do not hold.
545 .IP \(bu 4
546 Language classes may derive from other language classes (although they
547 should have "use \fIThatclassname\fR" or "use base qw(\fI...classes...\fR)").
548 They may derive from the project
549 class. They may derive from some other class altogether. Or via
550 multiple inheritance, it may derive from any mixture of these.
551 .IP \(bu 4
552 I foresee no problems with having multiple inheritance in
553 your hierarchy of language classes. (As usual, however, Perl will
554 complain bitterly if you have a cycle in the hierarchy: i.e., if
555 any class is its own ancestor.)
556 .SH "ENTRIES IN EACH LEXICON"
557 .IX Header "ENTRIES IN EACH LEXICON"
558 A typical \f(CW%Lexicon\fR entry is meant to signify a phrase,
559 taking some number (0 or more) of parameters. An entry
560 is meant to be accessed by via
561 a string \fIkey\fR in \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...),
562 which should return a string that is generally meant for
563 be used for "output" to the user \-\- regardless of whether
564 this actually means printing to STDOUT, writing to a file,
565 or putting into a GUI widget.
566 .PP
567 While the key must be a string value (since that's a basic
568 restriction that Perl places on hash keys), the value in
569 the lexicon can currently be of several types:
570 a defined scalar, scalarref, or coderef. The use of these is
571 explained above, in the section 'The "maketext" Method', and
572 Bracket Notation for strings is discussed in the next section.
573 .PP
574 While you can use arbitrary unique IDs for lexicon keys
575 (like "_min_larger_max_error"), it is often
576 useful for if an entry's key is itself a valid value, like
577 this example error message:
578 .PP
579 .Vb 1
580 \& "Minimum ([_1]) is larger than maximum ([_2])!\en",
581 .Ve
582 .PP
583 Compare this code that uses an arbitrary ID...
584 .PP
585 .Vb 2
586 \& die $lh\->maketext( "_min_larger_max_error", $min, $max )
587 \& if $min > $max;
588 .Ve
589 .PP
590 \&...to this code that uses a key-as-value:
591 .PP
592 .Vb 4
593 \& die $lh\->maketext(
594 \& "Minimum ([_1]) is larger than maximum ([_2])!\en",
595 \& $min, $max
596 \& ) if $min > $max;
597 .Ve
598 .PP
599 The second is, in short, more readable. In particular, it's obvious
600 that the number of parameters you're feeding to that phrase (two) is
601 the number of parameters that it \fIwants\fR to be fed. (Since you see
602 _1 and a _2 being used in the key there.)
603 .PP
604 Also, once a project is otherwise
605 complete and you start to localize it, you can scrape together
606 all the various keys you use, and pass it to a translator; and then
607 the translator's work will go faster if what he's presented is this:
608 .PP
609 .Vb 2
610 \& "Minimum ([_1]) is larger than maximum ([_2])!\en",
611 \& => "", # fill in something here, Jacques!
612 .Ve
613 .PP
614 rather than this more cryptic mess:
615 .PP
616 .Vb 2
617 \& "_min_larger_max_error"
618 \& => "", # fill in something here, Jacques
619 .Ve
620 .PP
621 I think that keys as lexicon values makes the completed lexicon
622 entries more readable:
623 .PP
624 .Vb 2
625 \& "Minimum ([_1]) is larger than maximum ([_2])!\en",
626 \& => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\en",
627 .Ve
628 .PP
629 Also, having valid values as keys becomes very useful if you set
630 up an _AUTO lexicon. _AUTO lexicons are discussed in a later
631 section.
632 .PP
633 I almost always use keys that are themselves
634 valid lexicon values. One notable exception is when the value is
635 quite long. For example, to get the screenful of data that
636 a command-line program might return when given an unknown switch,
637 I often just use a brief, self-explanatory key such as "_USAGE_MESSAGE". At that point I then go
638 and immediately to define that lexicon entry in the
639 ProjectClass::L10N::en lexicon (since English is always my "project
640 language"):
641 .PP
642 .Vb 3
643 \& \*(Aq_USAGE_MESSAGE\*(Aq => <<\*(AqEOSTUFF\*(Aq,
644 \& ...long long message...
645 \& EOSTUFF
646 .Ve
647 .PP
648 and then I can use it as:
649 .PP
650 .Vb 1
651 \& getopt(\*(AqoDI\*(Aq, \e%opts) or die $lh\->maketext(\*(Aq_USAGE_MESSAGE\*(Aq);
652 .Ve
653 .PP
654 Incidentally,
655 note that each class's \f(CW%Lexicon\fR inherits-and-extends
656 the lexicons in its superclasses. This is not because these are
657 special hashes \fIper se\fR, but because you access them via the
658 \&\f(CW\*(C`maketext\*(C'\fR method, which looks for entries across all the
659 \&\f(CW%Lexicon\fR hashes in a language class \fIand\fR all its ancestor classes.
660 (This is because the idea of "class data" isn't directly implemented
661 in Perl, but is instead left to individual class-systems to implement
662 as they see fit..)
663 .PP
664 Note that you may have things stored in a lexicon
665 besides just phrases for output: for example, if your program
666 takes input from the keyboard, asking a "(Y/N)" question,
667 you probably need to know what the equivalent of "Y[es]/N[o]" is
668 in whatever language. You probably also need to know what
669 the equivalents of the answers "y" and "n" are. You can
670 store that information in the lexicon (say, under the keys
671 "~answer_y" and "~answer_n", and the long forms as
672 "~answer_yes" and "~answer_no", where "~" is just an ad-hoc
673 character meant to indicate to programmers/translators that
674 these are not phrases for output).
675 .PP
676 Or instead of storing this in the language class's lexicon,
677 you can (and, in some cases, really should) represent the same bit
678 of knowledge as code in a method in the language class. (That
679 leaves a tidy distinction between the lexicon as the things we
680 know how to \fIsay\fR, and the rest of the things in the lexicon class
681 as things that we know how to \fIdo\fR.) Consider
682 this example of a processor for responses to French "oui/non"
683 questions:
684 .PP
685 .Vb 7
686 \& sub y_or_n {
687 \& return undef unless defined $_[1] and length $_[1];
688 \& my $answer = lc $_[1]; # smash case
689 \& return 1 if $answer eq \*(Aqo\*(Aq or $answer eq \*(Aqoui\*(Aq;
690 \& return 0 if $answer eq \*(Aqn\*(Aq or $answer eq \*(Aqnon\*(Aq;
691 \& return undef;
692 \& }
693 .Ve
694 .PP
695 \&...which you'd then call in a construct like this:
696 .PP
697 .Vb 7
698 \& my $response;
699 \& until(defined $response) {
700 \& print $lh\->maketext("Open the pod bay door (y/n)? ");
701 \& $response = $lh\->y_or_n( get_input_from_keyboard_somehow() );
702 \& }
703 \& if($response) { $pod_bay_door\->open() }
704 \& else { $pod_bay_door\->leave_closed() }
705 .Ve
706 .PP
707 Other data worth storing in a lexicon might be things like
708 filenames for language-targetted resources:
709 .PP
710 .Vb 10
711 \& ...
712 \& "_main_splash_png"
713 \& => "/styles/en_us/main_splash.png",
714 \& "_main_splash_imagemap"
715 \& => "/styles/en_us/main_splash.incl",
716 \& "_general_graphics_path"
717 \& => "/styles/en_us/",
718 \& "_alert_sound"
719 \& => "/styles/en_us/hey_there.wav",
720 \& "_forward_icon"
721 \& => "left_arrow.png",
722 \& "_backward_icon"
723 \& => "right_arrow.png",
724 \& # In some other languages, left equals
725 \& # BACKwards, and right is FOREwards.
726 \& ...
727 .Ve
728 .PP
729 You might want to do the same thing for expressing key bindings
730 or the like (since hardwiring "q" as the binding for the function
731 that quits a screen/menu/program is useful only if your language
732 happens to associate "q" with "quit"!)
733 .SH "BRACKET NOTATION"
734 .IX Header "BRACKET NOTATION"
735 Bracket Notation is a crucial feature of Locale::Maketext. I mean
736 Bracket Notation to provide a replacement for the use of sprintf formatting.
737 Everything you do with Bracket Notation could be done with a sub block,
738 but bracket notation is meant to be much more concise.
739 .PP
740 Bracket Notation is a like a miniature "template" system (in the sense
741 of Text::Template, not in the sense of C++ templates),
742 where normal text is passed thru basically as is, but text in special
743 regions is specially interpreted. In Bracket Notation, you use square brackets ("[...]"),
744 not curly braces ("{...}") to note sections that are specially interpreted.
745 .PP
746 For example, here all the areas that are taken literally are underlined with
747 a "^", and all the in-bracket special regions are underlined with an X:
748 .PP
749 .Vb 2
750 \& "Minimum ([_1]) is larger than maximum ([_2])!\en",
751 \& ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^
752 .Ve
753 .PP
754 When that string is compiled from bracket notation into a real Perl sub,
755 it's basically turned into:
756 .PP
757 .Vb 11
758 \& sub {
759 \& my $lh = $_[0];
760 \& my @params = @_;
761 \& return join \*(Aq\*(Aq,
762 \& "Minimum (",
763 \& ...some code here...
764 \& ") is larger than maximum (",
765 \& ...some code here...
766 \& ")!\en",
767 \& }
768 \& # to be called by $lh\->maketext(KEY, params...)
769 .Ve
770 .PP
771 In other words, text outside bracket groups is turned into string
772 literals. Text in brackets is rather more complex, and currently follows
773 these rules:
774 .IP \(bu 4
775 Bracket groups that are empty, or which consist only of whitespace,
776 are ignored. (Examples: "[]", "[ ]", or a [ and a ] with returns
777 and/or tabs and/or spaces between them.
778 .Sp
779 Otherwise, each group is taken to be a comma-separated group of items,
780 and each item is interpreted as follows:
781 .IP \(bu 4
782 An item that is "_\fIdigits\fR" or "_\-\fIdigits\fR" is interpreted as
783 \&\f(CW$_\fR[\fIvalue\fR]. I.e., "_1" becomes with \f(CW$_\fR[1], and "_\-3" is interpreted
784 as \f(CW$_\fR[\-3] (in which case \f(CW@_\fR should have at least three elements in it).
785 Note that \f(CW$_\fR[0] is the language handle, and is typically not named
786 directly.
787 .IP \(bu 4
788 An item "_*" is interpreted to mean "all of \f(CW@_\fR except \f(CW$_\fR[0]".
789 I.e., \f(CW@_[1..$#_]\fR. Note that this is an empty list in the case
790 of calls like \f(CW$lh\fR\->maketext(\fIkey\fR) where there are no
791 parameters (except \f(CW$_\fR[0], the language handle).
792 .IP \(bu 4
793 Otherwise, each item is interpreted as a string literal.
794 .PP
795 The group as a whole is interpreted as follows:
796 .IP \(bu 4
797 If the first item in a bracket group looks like a method name,
798 then that group is interpreted like this:
799 .Sp
800 .Vb 3
801 \& $lh\->that_method_name(
802 \& ...rest of items in this group...
803 \& ),
804 .Ve
805 .IP \(bu 4
806 If the first item in a bracket group is "*", it's taken as shorthand
807 for the so commonly called "quant" method. Similarly, if the first
808 item in a bracket group is "#", it's taken to be shorthand for
809 "numf".
810 .IP \(bu 4
811 If the first item in a bracket group is the empty-string, or "_*"
812 or "_\fIdigits\fR" or "_\-\fIdigits\fR", then that group is interpreted
813 as just the interpolation of all its items:
814 .Sp
815 .Vb 3
816 \& join(\*(Aq\*(Aq,
817 \& ...rest of items in this group...
818 \& ),
819 .Ve
820 .Sp
821 Examples: "[_1]" and "[,_1]", which are synonymous; and
822 "\f(CW\*(C`[,ID\-(,_4,\-,_2,)]\*(C'\fR", which compiles as
823 \&\f(CW\*(C`join "", "ID\-(", $_[4], "\-", $_[2], ")"\*(C'\fR.
824 .IP \(bu 4
825 Otherwise this bracket group is invalid. For example, in the group
826 "[!@#,whatever]", the first item \f(CW"!@#"\fR is neither the empty-string,
827 "_\fInumber\fR", "_\-\fInumber\fR", "_*", nor a valid method name; and so
828 Locale::Maketext will throw an exception of you try compiling an
829 expression containing this bracket group.
830 .PP
831 Note, incidentally, that items in each group are comma-separated,
832 not \f(CW\*(C`/\es*,\es*/\*(C'\fR\-separated. That is, you might expect that this
833 bracket group:
834 .PP
835 .Vb 1
836 \& "Hoohah [foo, _1 , bar ,baz]!"
837 .Ve
838 .PP
839 would compile to this:
840 .PP
841 .Vb 7
842 \& sub {
843 \& my $lh = $_[0];
844 \& return join \*(Aq\*(Aq,
845 \& "Hoohah ",
846 \& $lh\->foo( $_[1], "bar", "baz"),
847 \& "!",
848 \& }
849 .Ve
850 .PP
851 But it actually compiles as this:
852 .PP
853 .Vb 7
854 \& sub {
855 \& my $lh = $_[0];
856 \& return join \*(Aq\*(Aq,
857 \& "Hoohah ",
858 \& $lh\->foo(" _1 ", " bar ", "baz"), # note the <space> in " bar "
859 \& "!",
860 \& }
861 .Ve
862 .PP
863 In the notation discussed so far, the characters "[" and "]" are given
864 special meaning, for opening and closing bracket groups, and "," has
865 a special meaning inside bracket groups, where it separates items in the
866 group. This begs the question of how you'd express a literal "[" or
867 "]" in a Bracket Notation string, and how you'd express a literal
868 comma inside a bracket group. For this purpose I've adopted "~" (tilde)
869 as an escape character: "~[" means a literal '[' character anywhere
870 in Bracket Notation (i.e., regardless of whether you're in a bracket
871 group or not), and ditto for "~]" meaning a literal ']', and "~," meaning
872 a literal comma. (Altho "," means a literal comma outside of
873 bracket groups \-\- it's only inside bracket groups that commas are special.)
874 .PP
875 And on the off chance you need a literal tilde in a bracket expression,
876 you get it with "~~".
877 .PP
878 Currently, an unescaped "~" before a character
879 other than a bracket or a comma is taken to mean just a "~" and that
880 character. I.e., "~X" means the same as "~~X" \-\- i.e., one literal tilde,
881 and then one literal "X". However, by using "~X", you are assuming that
882 no future version of Maketext will use "~X" as a magic escape sequence.
883 In practice this is not a great problem, since first off you can just
884 write "~~X" and not worry about it; second off, I doubt I'll add lots
885 of new magic characters to bracket notation; and third off, you
886 aren't likely to want literal "~" characters in your messages anyway,
887 since it's not a character with wide use in natural language text.
888 .PP
889 Brackets must be balanced \-\- every openbracket must have
890 one matching closebracket, and vice versa. So these are all \fBinvalid\fR:
891 .PP
892 .Vb 4
893 \& "I ate [quant,_1,rhubarb pie."
894 \& "I ate [quant,_1,rhubarb pie[."
895 \& "I ate quant,_1,rhubarb pie]."
896 \& "I ate quant,_1,rhubarb pie[."
897 .Ve
898 .PP
899 Currently, bracket groups do not nest. That is, you \fBcannot\fR say:
900 .PP
901 .Vb 1
902 \& "Foo [bar,baz,[quux,quuux]]\en";
903 .Ve
904 .PP
905 If you need a notation that's that powerful, use normal Perl:
906 .PP
907 .Vb 11
908 \& %Lexicon = (
909 \& ...
910 \& "some_key" => sub {
911 \& my $lh = $_[0];
912 \& join \*(Aq\*(Aq,
913 \& "Foo ",
914 \& $lh\->bar(\*(Aqbaz\*(Aq, $lh\->quux(\*(Aqquuux\*(Aq)),
915 \& "\en",
916 \& },
917 \& ...
918 \& );
919 .Ve
920 .PP
921 Or write the "bar" method so you don't need to pass it the
922 output from calling quux.
923 .PP
924 I do not anticipate that you will need (or particularly want)
925 to nest bracket groups, but you are welcome to email me with
926 convincing (real-life) arguments to the contrary.
927 .SH "BRACKET NOTATION SECURITY"
928 .IX Header "BRACKET NOTATION SECURITY"
929 Locale::Maketext does not use any special syntax to differentiate
930 bracket notation methods from normal class or object methods. This
931 design makes it vulnerable to format string attacks whenever it is
932 used to process strings provided by untrusted users.
933 .PP
934 Locale::Maketext does support denylist and allowlist functionality
935 to limit which methods may be called as bracket notation methods.
936 .PP
937 By default, Locale::Maketext denies all methods in the
938 Locale::Maketext namespace that begin with the '_' character,
939 and all methods which include Perl's namespace separator characters.
940 .PP
941 The default denylist for Locale::Maketext also prevents use of the
942 following methods in bracket notation:
943 .PP
944 .Vb 10
945 \& denylist
946 \& encoding
947 \& fail_with
948 \& failure_handler_auto
949 \& fallback_language_classes
950 \& fallback_languages
951 \& get_handle
952 \& init
953 \& language_tag
954 \& maketext
955 \& new
956 \& allowlist
957 \& whitelist
958 \& blacklist
959 .Ve
960 .PP
961 This list can be extended by either deny-listing additional "known bad"
962 methods, or allow-listing only "known good" methods.
963 .PP
964 To prevent specific methods from being called in bracket notation, use
965 the \fBdenylist()\fR method:
966 .PP
967 .Vb 3
968 \& my $lh = MyProgram::L10N\->get_handle();
969 \& $lh\->denylist(qw{my_internal_method my_other_method});
970 \& $lh\->maketext(\*(Aq[my_internal_method]\*(Aq); # dies
971 .Ve
972 .PP
973 To limit the allowed bracked notation methods to a specific list, use the
974 \&\fBallowlist()\fR method:
975 .PP
976 .Vb 4
977 \& my $lh = MyProgram::L10N\->get_handle();
978 \& $lh\->allowlist(\*(Aqnumerate\*(Aq, \*(Aqnumf\*(Aq);
979 \& $lh\->maketext(\*(Aq[_1] [numerate, _1,shoe,shoes]\*(Aq, 12); # works
980 \& $lh\->maketext(\*(Aq[my_internal_method]\*(Aq); # dies
981 .Ve
982 .PP
983 The \fBdenylist()\fR and \fBallowlist()\fR methods extend their internal lists
984 whenever they are called. To reset the denylist or allowlist, create
985 a new maketext object.
986 .PP
987 .Vb 4
988 \& my $lh = MyProgram::L10N\->get_handle();
989 \& $lh\->denylist(\*(Aqnumerate\*(Aq);
990 \& $lh\->denylist(\*(Aqnumf\*(Aq);
991 \& $lh\->maketext(\*(Aq[_1] [numerate,_1,shoe,shoes]\*(Aq, 12); # dies
992 .Ve
993 .PP
994 For lexicons that use an internal cache, translations which have already
995 been cached in their compiled form are not affected by subsequent changes
996 to the allowlist or denylist settings. Lexicons that use an external
997 cache will have their cache cleared whenever the allowlist or denylist
998 settings change. The difference between the two types of caching is explained
999 in the "Readonly Lexicons" section.
1000 .PP
1001 Methods disallowed by the denylist cannot be permitted by the
1002 allowlist.
1003 .PP
1004 NOTE: \fBdenylist()\fR is the preferred method name to use instead of the
1005 historical and non-inclusive method \fBblacklist()\fR. \fBblacklist()\fR may be
1006 removed in a future release of this package and so it's use should be
1007 removed from usage.
1008 .PP
1009 NOTE: \fBallowlist()\fR is the preferred method name to use instead of the
1010 historical and non-inclusive method \fBwhitelist()\fR. \fBwhitelist()\fR may be
1011 removed in a future release of this package and so it's use should be
1012 removed from usage.
1013 .SH "AUTO LEXICONS"
1014 .IX Header "AUTO LEXICONS"
1015 If maketext goes to look in an individual \f(CW%Lexicon\fR for an entry
1016 for \fIkey\fR (where \fIkey\fR does not start with an underscore), and
1017 sees none, \fBbut does see\fR an entry of "_AUTO" => \fIsome_true_value\fR,
1018 then we actually define \f(CW$Lexicon\fR{\fIkey\fR} = \fIkey\fR right then and there,
1019 and then use that value as if it had been there all
1020 along. This happens before we even look in any superclass \f(CW%Lexicons\fR!
1021 .PP
1022 (This is meant to be somewhat like the AUTOLOAD mechanism in
1023 Perl's function call system \-\- or, looked at another way,
1024 like the AutoLoader module.)
1025 .PP
1026 I can picture all sorts of circumstances where you just
1027 do not want lookup to be able to fail (since failing
1028 normally means that maketext throws a \f(CW\*(C`die\*(C'\fR, although
1029 see the next section for greater control over that). But
1030 here's one circumstance where _AUTO lexicons are meant to
1031 be \fIespecially\fR useful:
1032 .PP
1033 As you're writing an application, you decide as you go what messages
1034 you need to emit. Normally you'd go to write this:
1035 .PP
1036 .Vb 5
1037 \& if(\-e $filename) {
1038 \& go_process_file($filename)
1039 \& } else {
1040 \& print qq{Couldn\*(Aqt find file "$filename"!\en};
1041 \& }
1042 .Ve
1043 .PP
1044 but since you anticipate localizing this, you write:
1045 .PP
1046 .Vb 10
1047 \& use ThisProject::I18N;
1048 \& my $lh = ThisProject::I18N\->get_handle();
1049 \& # For the moment, assume that things are set up so
1050 \& # that we load class ThisProject::I18N::en
1051 \& # and that that\*(Aqs the class that $lh belongs to.
1052 \& ...
1053 \& if(\-e $filename) {
1054 \& go_process_file($filename)
1055 \& } else {
1056 \& print $lh\->maketext(
1057 \& qq{Couldn\*(Aqt find file "[_1]"!\en}, $filename
1058 \& );
1059 \& }
1060 .Ve
1061 .PP
1062 Now, right after you've just written the above lines, you'd
1063 normally have to go open the file
1064 ThisProject/I18N/en.pm, and immediately add an entry:
1065 .PP
1066 .Vb 2
1067 \& "Couldn\*(Aqt find file \e"[_1]\e"!\en"
1068 \& => "Couldn\*(Aqt find file \e"[_1]\e"!\en",
1069 .Ve
1070 .PP
1071 But I consider that somewhat of a distraction from the work
1072 of getting the main code working \-\- to say nothing of the fact
1073 that I often have to play with the program a few times before
1074 I can decide exactly what wording I want in the messages (which
1075 in this case would require me to go changing three lines of code:
1076 the call to maketext with that key, and then the two lines in
1077 ThisProject/I18N/en.pm).
1078 .PP
1079 However, if you set "_AUTO => 1" in the \f(CW%Lexicon\fR in,
1080 ThisProject/I18N/en.pm (assuming that English (en) is
1081 the language that all your programmers will be using for this
1082 project's internal message keys), then you don't ever have to
1083 go adding lines like this
1084 .PP
1085 .Vb 2
1086 \& "Couldn\*(Aqt find file \e"[_1]\e"!\en"
1087 \& => "Couldn\*(Aqt find file \e"[_1]\e"!\en",
1088 .Ve
1089 .PP
1090 to ThisProject/I18N/en.pm, because if _AUTO is true there,
1091 then just looking for an entry with the key "Couldn't find
1092 file \e"[_1]\e"!\en" in that lexicon will cause it to be added,
1093 with that value!
1094 .PP
1095 Note that the reason that keys that start with "_"
1096 are immune to _AUTO isn't anything generally magical about
1097 the underscore character \-\- I just wanted a way to have most
1098 lexicon keys be autoable, except for possibly a few, and I
1099 arbitrarily decided to use a leading underscore as a signal
1100 to distinguish those few.
1101 .SH "READONLY LEXICONS"
1102 .IX Header "READONLY LEXICONS"
1103 If your lexicon is a tied hash the simple act of caching the compiled value can be fatal.
1104 .PP
1105 For example a GDBM_File GDBM_READER tied hash will die with something like:
1106 .PP
1107 .Vb 1
1108 \& gdbm store returned \-1, errno 2, key "..." at ...
1109 .Ve
1110 .PP
1111 All you need to do is turn on caching outside of the lexicon hash itself like so:
1112 .PP
1113 .Vb 6
1114 \& sub init {
1115 \& my ($lh) = @_;
1116 \& ...
1117 \& $lh\->{\*(Aquse_external_lex_cache\*(Aq} = 1;
1118 \& ...
1119 \& }
1120 .Ve
1121 .PP
1122 And then instead of storing the compiled value in the lexicon hash it will store it in \f(CW$lh\fR\->{'_external_lex_cache'}
1123 .SH "CONTROLLING LOOKUP FAILURE"
1124 .IX Header "CONTROLLING LOOKUP FAILURE"
1125 If you call \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...),
1126 and there's no entry \fIkey\fR in \f(CW$lh\fR's class's \f(CW%Lexicon\fR, nor
1127 in the superclass \f(CW%Lexicon\fR hash, \fIand\fR if we can't auto-make
1128 \&\fIkey\fR (because either it starts with a "_", or because none
1129 of its lexicons have \f(CW\*(C`_AUTO => 1,\*(C'\fR), then we have
1130 failed to find a normal way to maketext \fIkey\fR. What then
1131 happens in these failure conditions, depends on the \f(CW$lh\fR object's
1132 "fail" attribute.
1133 .PP
1134 If the language handle has no "fail" attribute, maketext
1135 will simply throw an exception (i.e., it calls \f(CW\*(C`die\*(C'\fR, mentioning
1136 the \fIkey\fR whose lookup failed, and naming the line number where
1137 the calling \f(CW$lh\fR\->maketext(\fIkey\fR,...) was.
1138 .PP
1139 If the language handle has a "fail" attribute whose value is a
1140 coderef, then \f(CW$lh\fR\->maketext(\fIkey\fR,...params...) gives up and calls:
1141 .PP
1142 .Vb 1
1143 \& return $that_subref\->($lh, $key, @params);
1144 .Ve
1145 .PP
1146 Otherwise, the "fail" attribute's value should be a string denoting
1147 a method name, so that \f(CW$lh\fR\->maketext(\fIkey\fR,...params...) can
1148 give up with:
1149 .PP
1150 .Vb 1
1151 \& return $lh\->$that_method_name($phrase, @params);
1152 .Ve
1153 .PP
1154 The "fail" attribute can be accessed with the \f(CW\*(C`fail_with\*(C'\fR method:
1155 .PP
1156 .Vb 2
1157 \& # Set to a coderef:
1158 \& $lh\->fail_with( \e&failure_handler );
1159 \&
1160 \& # Set to a method name:
1161 \& $lh\->fail_with( \*(Aqfailure_method\*(Aq );
1162 \&
1163 \& # Set to nothing (i.e., so failure throws a plain exception)
1164 \& $lh\->fail_with( undef );
1165 \&
1166 \& # Get the current value
1167 \& $handler = $lh\->fail_with();
1168 .Ve
1169 .PP
1170 Now, as to what you may want to do with these handlers: Maybe you'd
1171 want to log what key failed for what class, and then die. Maybe
1172 you don't like \f(CW\*(C`die\*(C'\fR and instead you want to send the error message
1173 to STDOUT (or wherever) and then merely \f(CWexit()\fR.
1174 .PP
1175 Or maybe you don't want to \f(CW\*(C`die\*(C'\fR at all! Maybe you could use a
1176 handler like this:
1177 .PP
1178 .Vb 10
1179 \& # Make all lookups fall back onto an English value,
1180 \& # but only after we log it for later fingerpointing.
1181 \& my $lh_backup = ThisProject\->get_handle(\*(Aqen\*(Aq);
1182 \& open(LEX_FAIL_LOG, ">>wherever/lex.log") || die "GNAARGH $!";
1183 \& sub lex_fail {
1184 \& my($failing_lh, $key, $params) = @_;
1185 \& print LEX_FAIL_LOG scalar(localtime), "\et",
1186 \& ref($failing_lh), "\et", $key, "\en";
1187 \& return $lh_backup\->maketext($key,@params);
1188 \& }
1189 .Ve
1190 .PP
1191 Some users have expressed that they think this whole mechanism of
1192 having a "fail" attribute at all, seems a rather pointless complication.
1193 But I want Locale::Maketext to be usable for software projects of \fIany\fR
1194 scale and type; and different software projects have different ideas
1195 of what the right thing is to do in failure conditions. I could simply
1196 say that failure always throws an exception, and that if you want to be
1197 careful, you'll just have to wrap every call to \f(CW$lh\fR\->maketext in an
1198 eval\ {\ }. However, I want programmers to reserve the right (via
1199 the "fail" attribute) to treat lookup failure as something other than
1200 an exception of the same level of severity as a config file being
1201 unreadable, or some essential resource being inaccessible.
1202 .PP
1203 One possibly useful value for the "fail" attribute is the method name
1204 "failure_handler_auto". This is a method defined in the class
1205 Locale::Maketext itself. You set it with:
1206 .PP
1207 .Vb 1
1208 \& $lh\->fail_with(\*(Aqfailure_handler_auto\*(Aq);
1209 .Ve
1210 .PP
1211 Then when you call \f(CW$lh\fR\->maketext(\fIkey\fR, ...parameters...) and
1212 there's no \fIkey\fR in any of those lexicons, maketext gives up with
1213 .PP
1214 .Vb 1
1215 \& return $lh\->failure_handler_auto($key, @params);
1216 .Ve
1217 .PP
1218 But failure_handler_auto, instead of dying or anything, compiles
1219 \&\f(CW$key\fR, caching it in
1220 .PP
1221 .Vb 1
1222 \& $lh\->{\*(Aqfailure_lex\*(Aq}{$key} = $compiled
1223 .Ve
1224 .PP
1225 and then calls the compiled value, and returns that. (I.e., if
1226 \&\f(CW$key\fR looks like bracket notation, \f(CW$compiled\fR is a sub, and we return
1227 &{$compiled}(@params); but if \f(CW$key\fR is just a plain string, we just
1228 return that.)
1229 .PP
1230 The effect of using "failure_auto_handler"
1231 is like an AUTO lexicon, except that it 1) compiles \f(CW$key\fR even if
1232 it starts with "_", and 2) you have a record in the new hashref
1233 \&\f(CW$lh\fR\->{'failure_lex'} of all the keys that have failed for
1234 this object. This should avoid your program dying \-\- as long
1235 as your keys aren't actually invalid as bracket code, and as
1236 long as they don't try calling methods that don't exist.
1237 .PP
1238 "failure_auto_handler" may not be exactly what you want, but I
1239 hope it at least shows you that maketext failure can be mitigated
1240 in any number of very flexible ways. If you can formalize exactly
1241 what you want, you should be able to express that as a failure
1242 handler. You can even make it default for every object of a given
1243 class, by setting it in that class's init:
1244 .PP
1245 .Vb 9
1246 \& sub init {
1247 \& my $lh = $_[0]; # a newborn handle
1248 \& $lh\->SUPER::init();
1249 \& $lh\->fail_with(\*(Aqmy_clever_failure_handler\*(Aq);
1250 \& return;
1251 \& }
1252 \& sub my_clever_failure_handler {
1253 \& ...you clever things here...
1254 \& }
1255 .Ve
1256 .SH "HOW TO USE MAKETEXT"
1257 .IX Header "HOW TO USE MAKETEXT"
1258 Here is a brief checklist on how to use Maketext to localize
1259 applications:
1260 .IP \(bu 4
1261 Decide what system you'll use for lexicon keys. If you insist,
1262 you can use opaque IDs (if you're nostalgic for \f(CW\*(C`catgets\*(C'\fR),
1263 but I have better suggestions in the
1264 section "Entries in Each Lexicon", above. Assuming you opt for
1265 meaningful keys that double as values (like "Minimum ([_1]) is
1266 larger than maximum ([_2])!\en"), you'll have to settle on what
1267 language those should be in. For the sake of argument, I'll
1268 call this English, specifically American English, "en-US".
1269 .IP \(bu 4
1270 Create a class for your localization project. This is
1271 the name of the class that you'll use in the idiom:
1272 .Sp
1273 .Vb 2
1274 \& use Projname::L10N;
1275 \& my $lh = Projname::L10N\->get_handle(...) || die "Language?";
1276 .Ve
1277 .Sp
1278 Assuming you call your class Projname::L10N, create a class
1279 consisting minimally of:
1280 .Sp
1281 .Vb 3
1282 \& package Projname::L10N;
1283 \& use base qw(Locale::Maketext);
1284 \& ...any methods you might want all your languages to share...
1285 \&
1286 \& # And, assuming you want the base class to be an _AUTO lexicon,
1287 \& # as is discussed a few sections up:
1288 \&
1289 \& 1;
1290 .Ve
1291 .IP \(bu 4
1292 Create a class for the language your internal keys are in. Name
1293 the class after the language-tag for that language, in lowercase,
1294 with dashes changed to underscores. Assuming your project's first
1295 language is US English, you should call this Projname::L10N::en_us.
1296 It should consist minimally of:
1297 .Sp
1298 .Vb 6
1299 \& package Projname::L10N::en_us;
1300 \& use base qw(Projname::L10N);
1301 \& %Lexicon = (
1302 \& \*(Aq_AUTO\*(Aq => 1,
1303 \& );
1304 \& 1;
1305 .Ve
1306 .Sp
1307 (For the rest of this section, I'll assume that this "first
1308 language class" of Projname::L10N::en_us has
1309 _AUTO lexicon.)
1310 .IP \(bu 4
1311 Go and write your program. Everywhere in your program where
1312 you would say:
1313 .Sp
1314 .Vb 1
1315 \& print "Foobar $thing stuff\en";
1316 .Ve
1317 .Sp
1318 instead do it thru maketext, using no variable interpolation in
1319 the key:
1320 .Sp
1321 .Vb 1
1322 \& print $lh\->maketext("Foobar [_1] stuff\en", $thing);
1323 .Ve
1324 .Sp
1325 If you get tired of constantly saying \f(CW\*(C`print $lh\->maketext\*(C'\fR,
1326 consider making a functional wrapper for it, like so:
1327 .Sp
1328 .Vb 7
1329 \& use Projname::L10N;
1330 \& our $lh;
1331 \& $lh = Projname::L10N\->get_handle(...) || die "Language?";
1332 \& sub pmt (@) { print( $lh\->maketext(@_)) }
1333 \& # "pmt" is short for "Print MakeText"
1334 \& $Carp::Verbose = 1;
1335 \& # so if maketext fails, we see made the call to pmt
1336 .Ve
1337 .Sp
1338 Besides whole phrases meant for output, anything language-dependent
1339 should be put into the class Projname::L10N::en_us,
1340 whether as methods, or as lexicon entries \-\- this is discussed
1341 in the section "Entries in Each Lexicon", above.
1342 .IP \(bu 4
1343 Once the program is otherwise done, and once its localization for
1344 the first language works right (via the data and methods in
1345 Projname::L10N::en_us), you can get together the data for translation.
1346 If your first language lexicon isn't an _AUTO lexicon, then you already
1347 have all the messages explicitly in the lexicon (or else you'd be
1348 getting exceptions thrown when you call \f(CW$lh\fR\->maketext to get
1349 messages that aren't in there). But if you were (advisedly) lazy and are
1350 using an _AUTO lexicon, then you've got to make a list of all the phrases
1351 that you've so far been letting _AUTO generate for you. There are very
1352 many ways to assemble such a list. The most straightforward is to simply
1353 grep the source for every occurrence of "maketext" (or calls
1354 to wrappers around it, like the above \f(CW\*(C`pmt\*(C'\fR function), and to log the
1355 following phrase.
1356 .IP \(bu 4
1357 You may at this point want to consider whether your base class
1358 (Projname::L10N), from which all lexicons inherit from (Projname::L10N::en,
1359 Projname::L10N::es, etc.), should be an _AUTO lexicon. It may be true
1360 that in theory, all needed messages will be in each language class;
1361 but in the presumably unlikely or "impossible" case of lookup failure,
1362 you should consider whether your program should throw an exception,
1363 emit text in English (or whatever your project's first language is),
1364 or some more complex solution as described in the section
1365 "Controlling Lookup Failure", above.
1366 .IP \(bu 4
1367 Submit all messages/phrases/etc. to translators.
1368 .Sp
1369 (You may, in fact, want to start with localizing to \fIone\fR other language
1370 at first, if you're not sure that you've properly abstracted the
1371 language-dependent parts of your code.)
1372 .Sp
1373 Translators may request clarification of the situation in which a
1374 particular phrase is found. For example, in English we are entirely happy
1375 saying "\fIn\fR files found", regardless of whether we mean "I looked for files,
1376 and found \fIn\fR of them" or the rather distinct situation of "I looked for
1377 something else (like lines in files), and along the way I saw \fIn\fR
1378 files." This may involve rethinking things that you thought quite clear:
1379 should "Edit" on a toolbar be a noun ("editing") or a verb ("to edit")? Is
1380 there already a conventionalized way to express that menu option, separate
1381 from the target language's normal word for "to edit"?
1382 .Sp
1383 In all cases where the very common phenomenon of quantification
1384 (saying "\fIN\fR files", for \fBany\fR value of N)
1385 is involved, each translator should make clear what dependencies the
1386 number causes in the sentence. In many cases, dependency is
1387 limited to words adjacent to the number, in places where you might
1388 expect them ("I found the\-?PLURAL \fIN\fR
1389 empty\-?PLURAL directory\-?PLURAL"), but in some cases there are
1390 unexpected dependencies ("I found\-?PLURAL ..."!) as well as long-distance
1391 dependencies "The \fIN\fR directory\-?PLURAL could not be deleted\-?PLURAL"!).
1392 .Sp
1393 Remind the translators to consider the case where N is 0:
1394 "0 files found" isn't exactly natural-sounding in any language, but it
1395 may be unacceptable in many \-\- or it may condition special
1396 kinds of agreement (similar to English "I didN'T find ANY files").
1397 .Sp
1398 Remember to ask your translators about numeral formatting in their
1399 language, so that you can override the \f(CW\*(C`numf\*(C'\fR method as
1400 appropriate. Typical variables in number formatting are: what to
1401 use as a decimal point (comma? period?); what to use as a thousands
1402 separator (space? nonbreaking space? comma? period? small
1403 middot? prime? apostrophe?); and even whether the so-called "thousands
1404 separator" is actually for every third digit \-\- I've heard reports of
1405 two hundred thousand being expressible as "2,00,000" for some Indian
1406 (Subcontinental) languages, besides the less surprising "200\ 000",
1407 "200.000", "200,000", and "200'000". Also, using a set of numeral
1408 glyphs other than the usual ASCII "0"\-"9" might be appreciated, as via
1409 \&\f(CW\*(C`tr/0\-9/\ex{0966}\-\ex{096F}/\*(C'\fR for getting digits in Devanagari script
1410 (for Hindi, Konkani, others).
1411 .Sp
1412 The basic \f(CW\*(C`quant\*(C'\fR method that Locale::Maketext provides should be
1413 good for many languages. For some languages, it might be useful
1414 to modify it (or its constituent \f(CW\*(C`numerate\*(C'\fR method)
1415 to take a plural form in the two-argument call to \f(CW\*(C`quant\*(C'\fR
1416 (as in "[quant,_1,files]") if
1417 it's all-around easier to infer the singular form from the plural, than
1418 to infer the plural form from the singular.
1419 .Sp
1420 But for other languages (as is discussed at length
1421 in Locale::Maketext::TPJ13), simple
1422 \&\f(CW\*(C`quant\*(C'\fR/\f(CW\*(C`numf\*(C'\fR is not enough. For the particularly problematic
1423 Slavic languages, what you may need is a method which you provide
1424 with the number, the citation form of the noun to quantify, and
1425 the case and gender that the sentence's syntax projects onto that
1426 noun slot. The method would then be responsible for determining
1427 what grammatical number that numeral projects onto its noun phrase,
1428 and what case and gender it may override the normal case and gender
1429 with; and then it would look up the noun in a lexicon providing
1430 all needed inflected forms.
1431 .IP \(bu 4
1432 You may also wish to discuss with the translators the question of
1433 how to relate different subforms of the same language tag,
1434 considering how this reacts with \f(CW\*(C`get_handle\*(C'\fR's treatment of
1435 these. For example, if a user accepts interfaces in "en, fr", and
1436 you have interfaces available in "en-US" and "fr", what should
1437 they get? You may wish to resolve this by establishing that "en"
1438 and "en-US" are effectively synonymous, by having one class
1439 zero-derive from the other.
1440 .Sp
1441 For some languages this issue may never come up (Danish is rarely
1442 expressed as "da-DK", but instead is just "da"). And for other
1443 languages, the whole concept of a "generic" form may verge on
1444 being uselessly vague, particularly for interfaces involving voice
1445 media in forms of Arabic or Chinese.
1446 .IP \(bu 4
1447 Once you've localized your program/site/etc. for all desired
1448 languages, be sure to show the result (whether live, or via
1449 screenshots) to the translators. Once they approve, make every
1450 effort to have it then checked by at least one other speaker of
1451 that language. This holds true even when (or especially when) the
1452 translation is done by one of your own programmers. Some
1453 kinds of systems may be harder to find testers for than others,
1454 depending on the amount of domain-specific jargon and concepts
1455 involved \-\- it's easier to find people who can tell you whether
1456 they approve of your translation for "delete this message" in an
1457 email-via-Web interface, than to find people who can give you
1458 an informed opinion on your translation for "attribute value"
1459 in an XML query tool's interface.
1460 .SH "SEE ALSO"
1461 .IX Header "SEE ALSO"
1462 I recommend reading all of these:
1463 .PP
1464 Locale::Maketext::TPJ13 \-\- my \fIThe Perl
1465 Journal\fR article about Maketext. It explains many important concepts
1466 underlying Locale::Maketext's design, and some insight into why
1467 Maketext is better than the plain old approach of having
1468 message catalogs that are just databases of sprintf formats.
1469 .PP
1470 File::Findgrep is a sample application/module
1471 that uses Locale::Maketext to localize its messages. For a larger
1472 internationalized system, see also Apache::MP3.
1473 .PP
1474 I18N::LangTags.
1475 .PP
1476 Win32::Locale.
1477 .PP
1478 RFC 3066, \fITags for the Identification of Languages\fR,
1479 as at <http://sunsite.dk/RFC/rfc/rfc3066.html>
1480 .PP
1481 RFC 2277, \fIIETF Policy on Character Sets and Languages\fR
1482 is at <http://sunsite.dk/RFC/rfc/rfc2277.html> \-\- much of it is
1483 just things of interest to protocol designers, but it explains
1484 some basic concepts, like the distinction between locales and
1485 language-tags.
1486 .PP
1487 The manual for GNU \f(CW\*(C`gettext\*(C'\fR. The gettext dist is available in
1488 \&\f(CW\*(C`<ftp://prep.ai.mit.edu/pub/gnu/>\*(C'\fR \-\- get
1489 a recent gettext tarball and look in its "doc/" directory, there's
1490 an easily browsable HTML version in there. The
1491 gettext documentation asks lots of questions worth thinking
1492 about, even if some of their answers are sometimes wonky,
1493 particularly where they start talking about pluralization.
1494 .PP
1495 The Locale/Maketext.pm source. Observe that the module is much
1496 shorter than its documentation!
1497 .SH "COPYRIGHT AND DISCLAIMER"
1498 .IX Header "COPYRIGHT AND DISCLAIMER"
1499 Copyright (c) 1999\-2004 Sean M. Burke. All rights reserved.
1500 .PP
1501 This library is free software; you can redistribute it and/or modify
1502 it under the same terms as Perl itself.
1503 .PP
1504 This program is distributed in the hope that it will be useful, but
1505 without any warranty; without even the implied warranty of
1506 merchantability or fitness for a particular purpose.
1507 .SH AUTHOR
1508 .IX Header "AUTHOR"
1509 Sean M. Burke \f(CW\*(C`[email protected]\*(C'\fR