Debian Codegraph @

upstream/mageia-cauldron/man3pm/Locale::Maketext.3pm

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