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