2 # Time-stamp: "2001-06-20 02:02:33 MDT"
6 Locale::Maketext -- framework for localization
13 # ...which inherits from Locale::Maketext
14 my $lh = MyProgram::L10N->get_handle() || die "What language?";
16 # And then any messages your program emits, like:
17 warn $lh->maketext( "Can't open file [_1]: [_2]\n", $f, $! );
22 It is a common feature of applications (whether run directly,
23 or via the Web) for them to be "localized" -- i.e., for them
24 to a present an English interface to an English-speaker, a German
25 interface to a German-speaker, and so on for all languages it's
26 programmed with. Locale::Maketext
27 is a framework for software localization; it provides you with the
28 tools for organizing and accessing the bits of text and text-processing
29 code that you need for producing localized applications.
31 In order to make sense of Maketext and how all its
32 components fit together, you should probably
33 go read L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>, and
34 I<then> read the following documentation.
36 You may also want to read over the source for C<File::Findgrep>
37 and its constituent modules -- they are a complete (if small)
38 example application that uses Maketext.
42 The basic design of Locale::Maketext is object-oriented, and
43 Locale::Maketext is an abstract base class, from which you
44 derive a "project class".
45 The project class (with a name like "TkBocciBall::Localize",
46 which you then use in your module) is in turn the base class
47 for all the "language classes" for your project
48 (with names "TkBocciBall::Localize::it",
49 "TkBocciBall::Localize::en",
50 "TkBocciBall::Localize::fr", etc.).
53 a class containing a lexicon of phrases as class data,
54 and possibly also some methods that are of use in interpreting
55 phrases in the lexicon, or otherwise dealing with text in that
58 An object belonging to a language class is called a "language
59 handle"; it's typically a flyweight object.
61 The normal course of action is to call:
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;
70 From then on, you use the C<maketext> function to access
71 entries in whatever lexicon(s) belong to the language handle
74 print $lh->maketext("You won!"), "\n";
76 ...emits the right text for this language. If the object
77 in 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
80 code happily tells the user "Tu as gagnE<eacute>!".
84 Locale::Maketext offers a variety of methods, which fall
85 into three categories:
91 Methods to do with constructing language handles.
95 C<maketext> and other methods to do with accessing %Lexicon data
96 for a given language handle.
100 Methods that you may find it handy to use, from routines of
101 yours that you put in %Lexicon entries.
105 These are covered in the following section.
107 =head2 Construction Methods
109 These are to do with constructing a language handle:
113 =item $lh = YourProjClass->get_handle( ...langtags... ) || die "lg-handle?";
115 This tries loading classes based on the language-tags you give (like
116 C<("en-US", "sk", "kon", "es-MX", "ja", "i-klingon")>, and for the first class
117 that succeeds, returns YourProjClass::I<language>->new().
119 It runs thru the entire given list of language-tags, and finds no classes
120 for those exact terms, it then tries "superordinate" language classes.
121 So if no "en-US" class (i.e., YourProjClass::en_us)
122 was found, nor classes for anything else in that list, we then try
123 its superordinate, "en" (i.e., YourProjClass::en), and so on thru
124 the other language-tags in the given list: "es".
125 (The other language-tags in our example list:
126 happen to have no superordinates.)
128 If none of those language-tags leads to loadable classes, we then
129 try classes derived from YourProjClass->fallback_languages() and
130 then if nothing comes of that, we use classes named by
131 YourProjClass->fallback_language_classes(). Then in the (probably
132 quite unlikely) event that that fails, we just return undef.
134 =item $lh = YourProjClass->get_handleB<()> || die "lg-handle?";
136 When C<get_handle> is called with an empty parameter list, magic happens:
138 If C<get_handle> senses that it's running in program that was
139 invoked as a CGI, then it tries to get language-tags out of the
140 environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that
141 those were the languages passed as parameters to C<get_handle>.
143 Otherwise (i.e., if not a CGI), this tries various OS-specific ways
144 to get the language-tags for the current locale/language, and then
145 pretends that those were the value(s) passed to C<cet_handle>.
147 Currently this OS-specific stuff consists of looking in the environment
148 variables "LANG" and "LANGUAGE"; and on MSWin machines (where those
149 variables are typically unused), this also tries using
150 the module Win32::Locale to get a language-tag for whatever language/locale
151 is currently selected in the "Regional Settings" (or "International"?)
152 Control Panel. I welcome further
153 suggestions for making this do the Right Thing under other operating
154 systems that support localization.
156 If you're using localization in an application that keeps a configuration
157 file, you might consider something like this in your project class:
159 sub get_handle_via_config {
161 my $preferred_language = $Config_settings{'language'};
163 if($preferred_language) {
164 $lh = $class->get_handle($chosen_language)
165 || die "No language handle for \"$chosen_language\" or the like";
167 # Config file missing, maybe?
168 $lh = $class->get_handle()
169 || die "Can't get a language handle";
174 =item $lh = YourProjClass::langname->new();
176 This constructs a language handle. You usually B<don't> call this
177 directly, but instead let C<get_handle> find a language class to C<use>
178 and to then call ->new on.
182 This is called by ->new to initialize newly-constructed language handles.
183 If you define an init method in your class, remember that it's usually
184 considered a good idea to call $lh->SUPER::init in it (presumably at the
185 beginning), so that all classes get a chance to initialize a new object
186 however they see fit.
188 =item YourProjClass->fallback_languages()
190 C<get_handle> appends the return value of this to the end of
191 whatever list of languages you pass C<get_handle>. Unless
192 you override this method, your project class
193 will inherit Locale::Maketext's C<fallback_languages>, which
194 currently returns C<('i-default', 'en', 'en-US')>.
195 ("i-default" is defined in RFC 2277).
197 This method (by having it return the name
198 of a language-tag that has an existing language class)
199 can be used for making sure that
200 C<get_handle> will always manage to construct a language
201 handle (assuming your language classes are in an appropriate
202 @INC directory). Or you can use the next method:
204 =item YourProjClass->fallback_language_classes()
206 C<get_handle> appends the return value of this to the end
207 of the list of classes it will try using. Unless
208 you override this method, your project class
209 will inherit Locale::Maketext's C<fallback_language_classes>,
210 which currently returns an empty list, C<()>.
211 By setting this to some value (namely, the name of a loadable
212 language class), you can be sure that
213 C<get_handle> will always manage to construct a language
218 =head2 The "maketext" Method
220 This is the most important method in Locale::Maketext:
222 $text = $lh->maketext(I<key>, ...parameters for this phrase...);
224 This looks in the %Lexicon of the language handle
225 $lh and all its superclasses, looking
226 for an entry whose key is the string I<key>. Assuming such
227 an entry is found, various things then happen, depending on the
230 If the value is a scalarref, the scalar is dereferenced and returned
231 (and any parameters are ignored).
232 If the value is a coderef, we return &$value($lh, ...parameters...).
233 If the value is a string that I<doesn't> look like it's in Bracket Notation,
234 we return it (after replacing it with a scalarref, in its %Lexicon).
235 If the value I<does> look like it's in Bracket Notation, then we compile
236 it into a sub, replace the string in the %Lexicon with the new coderef,
237 and then we return &$new_sub($lh, ...parameters...).
239 Bracket Notation is discussed in a later section. Note
240 that trying to compile a string into Bracket Notation can throw
241 an exception if the string is not syntactically valid (say, by not
242 balancing brackets right.)
244 Also, calling &$coderef($lh, ...parameters...) can throw any sort of
245 exception (if, say, code in that sub tries to divide by zero). But
246 a very common exception occurs when you have Bracket
247 Notation text that says to call a method "foo", but there is no such
248 method. (E.g., "You have [quaB<tn>,_1,ball]." will throw an exception
249 on trying to call $lh->quaB<tn>($_[1],'ball') -- you presumably meant
250 "quant".) C<maketext> catches these exceptions, but only to make the
251 error message more readable, at which point it rethrows the exception.
253 An exception I<may> be thrown if I<key> is not found in any
254 of $lh's %Lexicon hashes. What happens if a key is not found,
255 is discussed in a later section, "Controlling Lookup Failure".
257 Note that you might find it useful in some cases to override
258 the C<maketext> method with an "after method", if you want to
259 translate encodings, or even scripts:
261 package YrProj::zh_cn; # Chinese with PRC-style glyphs
262 use base ('YrProj::zh_tw'); # Taiwan-style
264 my $self = shift(@_);
265 my $value = $self->maketext(@_);
266 return Chineeze::taiwan2mainland($value);
269 Or you may want to override it with something that traps
270 any exceptions, if that's critical to your program:
273 my($lh, @stuff) = @_;
275 eval { $out = $lh->SUPER::maketext(@stuff) };
276 return $out unless $@;
277 ...otherwise deal with the exception...
280 Other than those two situations, I don't imagine that
281 it's useful to override the C<maketext> method. (If
282 you run into a situation where it is useful, I'd be
283 interested in hearing about it.)
287 =item $lh->fail_with I<or> $lh->fail_with(I<PARAM>)
289 =item $lh->failure_handler_auto
291 These two methods are discussed in the section "Controlling
296 =head2 Utility Methods
298 These are methods that you may find it handy to use, generally
299 from %Lexicon routines of yours (whether expressed as
300 Bracket Notation or not).
304 =item $language->quant($number, $singular)
306 =item $language->quant($number, $singular, $plural)
308 =item $language->quant($number, $singular, $plural, $negative)
310 This is generally meant to be called from inside Bracket Notation
311 (which is discussed later), as in
313 "Your search matched [quant,_1,document]!"
315 It's for I<quantifying> a noun (i.e., saying how much of it there is,
316 while giving the currect form of it). The behavior of this method is
317 handy for English and a few other Western European languages, and you
318 should override it for languages where it's not suitable. You can feel
319 free to read the source, but the current implementation is basically
320 as this pseudocode describes:
322 if $number is 0 and there's a $negative,
325 return "1 $singular";
326 elsif there's a $plural,
327 return "$number $plural";
329 return "$number " . $singular . "s";
331 # ...except that we actually call numf to
332 # stringify $number before returning it.
334 So for English (with Bracket Notation)
335 C<"...[quant,_1,file]..."> is fine (for 0 it returns "0 files",
336 for 1 it returns "1 file", and for more it returns "2 files", etc.)
338 But for "directory", you'd want C<"[quant,_1,direcory,directories]">
339 so that our elementary C<quant> method doesn't think that the
340 plural of "directory" is "directorys". And you might find that the
341 output may sound better if you specify a negative form, as in:
343 "[quant,_1,file,files,No files] matched your query.\n"
345 Remember to keep in mind verb agreement (or adjectives too, in
346 other languages), as in:
348 "[quant,_1,document] were matched.\n"
350 Because if _1 is one, you get "1 document B<were> matched".
351 An acceptable hack here is to do something like this:
353 "[quant,_1,document was, documents were] matched.\n"
355 =item $language->numf($number)
357 This returns the given number formatted nicely according to
358 this language's conventions. Maketext's default method is
359 mostly to just take the normal string form of the number
360 (applying sprintf "%G" for only very large numbers), and then
361 to add commas as necessary. (Except that
362 we apply C<tr/,./.,/> if $language->{'numf_comma'} is true;
363 that's a bit of a hack that's useful for languages that express
364 two million as "2.000.000" and not as "2,000,000").
366 If you want anything fancier, consider overriding this with something
367 that uses L<Number::Format|Number::Format>, or does something else
370 Note that numf is called by quant for stringifying all quantifying
373 =item $language->sprintf($format, @items)
375 This is just a wrapper around Perl's normal C<sprintf> function.
376 It's provided so that you can use "sprintf" in Bracket Notation:
378 "Couldn't access datanode [sprintf,%10x=~[%s~],_1,_2]!\n"
382 Couldn't access datanode Stuff=[thangamabob]!
384 =item $language->language_tag()
386 Currently this just takes the last bit of C<ref($language)>, turns
387 underscores to dashes, and returns it. So if $language is
388 an object of class Hee::HOO::Haw::en_us, $language->language_tag()
389 returns "en-us". (Yes, the usual representation for that language
390 tag is "en-US", but case is I<never> considered meaningful in
391 language-tag comparison.)
393 You may override this as you like; Maketext doesn't use it for
396 =item $language->encoding()
398 Currently this isn't used for anything, but it's provided
399 (with default value of
400 C<(ref($language) && $language-E<gt>{'encoding'})) or "iso-8859-1">
401 ) as a sort of suggestion that it may be useful/necessary to
402 associate encodings with your language handles (whether on a
403 per-class or even per-handle basis.)
407 =head2 Language Handle Attributes and Internals
409 A language handle is a flyweight object -- i.e., it doesn't (necessarily)
410 carry any data of interest, other than just being a member of
411 whatever class it belongs to.
413 A language handle is implemented as a blessed hash. Subclasses of yours
414 can store whatever data you want in the hash. Currently the only hash
415 entry used by any crucial Maketext method is "fail", so feel free to
416 use anything else as you like.
418 B<Remember: Don't be afraid to read the Maketext source if there's
419 any point on which this documentation is unclear.> This documentation
420 is vastly longer than the module source itself.
426 =head1 LANGUAGE CLASS HIERARCHIES
428 These are Locale::Maketext's assumptions about the class
429 hierarchy formed by all your language classes:
435 You must have a project base class, which you load, and
436 which you then use as the first argument in
437 the call to YourProjClass->get_handle(...). It should derive
438 (whether directly or indirectly) from Locale::Maketext.
439 It B<doesn't matter> how you name this class, altho assuming this
440 is the localization component of your Super Mega Program,
441 good names for your project class might be
442 SuperMegaProgram::Localization, SuperMegaProgram::L10N,
443 SuperMegaProgram::I18N, SuperMegaProgram::International,
444 or even SuperMegaProgram::Languages or SuperMegaProgram::Messages.
448 Language classes are what YourProjClass->get_handle will try to load.
449 It will look for them by taking each language-tag (B<skipping> it
450 if it doesn't look like a language-tag or locale-tag!), turning it to
451 all lowercase, turning and dashes to underscores, and appending it
452 to YourProjClass . "::". So this:
454 $lh = YourProjClass->get_handle(
455 'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized'
458 will try loading the classes
459 YourProjClass::en_us (note lowercase!), YourProjClass::fr,
461 YourProjClass::i_klingon
462 and YourProjClass::i_klingon_romanized. (And it'll stop at the
463 first one that actually loads.)
467 I assume that each language class derives (directly or indirectly)
468 from your project class, and also defines its @ISA, its %Lexicon,
469 or both. But I anticipate no dire consequences if these assumptions
474 Language classes may derive from other language classes (altho they
475 should have "use I<Thatclassname>" or "use base qw(I<...classes...>)").
476 They may derive from the project
477 class. They may derive from some other class altogether. Or via
478 multiple inheritance, it may derive from any mixture of these.
482 I foresee no problems with having multiple inheritance in
483 your hierarchy of language classes. (As usual, however, Perl will
484 complain bitterly if you have a cycle in the hierarchy: i.e., if
485 any class is its own ancestor.)
489 =head1 ENTRIES IN EACH LEXICON
491 A typical %Lexicon entry is meant to signify a phrase,
492 taking some number (0 or more) of parameters. An entry
493 is meant to be accessed by via
494 a string I<key> in $lh->maketext(I<key>, ...parameters...),
495 which should return a string that is generally meant for
496 be used for "output" to the user -- regardless of whether
497 this actually means printing to STDOUT, writing to a file,
498 or putting into a GUI widget.
500 While the key must be a string value (since that's a basic
501 restriction that Perl places on hash keys), the value in
502 the lexicon can currenly be of several types:
503 a defined scalar, scalarref, or coderef. The use of these is
504 explained above, in the section 'The "maketext" Method', and
505 Bracket Notation for strings is discussed in the next section.
507 While you can use arbitrary unique IDs for lexicon keys
508 (like "_min_larger_max_error"), it is often
509 useful for if an entry's key is itself a valid value, like
510 this example error message:
512 "Minimum ([_1]) is larger than maximum ([_2])!\n",
514 Compare this code that uses an arbitrary ID...
516 die $lh->maketext( "_min_larger_max_error", $min, $max )
519 ...to this code that uses a key-as-value:
522 "Minimum ([_1]) is larger than maximum ([_2])!\n",
526 The second is, in short, more readable. In particular, it's obvious
527 that the number of parameters you're feeding to that phrase (two) is
528 the number of parameters that it I<wants> to be fed. (Since you see
529 _1 and a _2 being used in the key there.)
531 Also, once a project is otherwise
532 complete and you start to localize it, you can scrape together
533 all the various keys you use, and pass it to a translator; and then
534 the translator's work will go faster if what he's presented is this:
536 "Minimum ([_1]) is larger than maximum ([_2])!\n",
537 => "", # fill in something here, Jacques!
539 rather than this more cryptic mess:
541 "_min_larger_max_error"
542 => "", # fill in something here, Jacques
544 I think that keys as lexicon values makes the completed lexicon
545 entries more readable:
547 "Minimum ([_1]) is larger than maximum ([_2])!\n",
548 => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\n",
550 Also, having valid values as keys becomes very useful if you set
551 up an _AUTO lexicon. _AUTO lexicons are discussed in a later
554 I almost always use keys that are themselves
555 valid lexicon values. One notable exception is when the value is
556 quite long. For example, to get the screenful of data that
557 a command-line program might returns when given an unknown switch,
558 I often just use a key "_USAGE_MESSAGE". At that point I then go
559 and immediately to define that lexicon entry in the
560 ProjectClass::L10N::en lexicon (since English is always my "project
563 '_USAGE_MESSAGE' => <<'EOSTUFF',
564 ...long long message...
567 and then I can use it as:
569 getopt('oDI', \%opts) or die $lh->maketext('_USAGE_MESSAGE');
572 note that each class's C<%Lexicon> inherits-and-extends
573 the lexicons in its superclasses. This is not because these are
574 special hashes I<per se>, but because you access them via the
575 C<maketext> method, which looks for entries across all the
576 C<%Lexicon>'s in a language class I<and> all its ancestor classes.
577 (This is because the idea of "class data" isn't directly implemented
578 in Perl, but is instead left to individual class-systems to implement
581 Note that you may have things stored in a lexicon
582 besides just phrases for output: for example, if your program
583 takes input from the keyboard, asking a "(Y/N)" question,
584 you probably need to know what equivalent of "Y[es]/N[o]" is
585 in whatever language. You probably also need to know what
586 the equivalents of the answers "y" and "n" are. You can
587 store that information in the lexicon (say, under the keys
588 "~answer_y" and "~answer_n", and the long forms as
589 "~answer_yes" and "~answer_no", where "~" is just an ad-hoc
590 character meant to indicate to programmers/translators that
591 these are not phrases for output).
593 Or instead of storing this in the language class's lexicon,
594 you can (and, in some cases, really should) represent the same bit
595 of knowledge as code is a method in the language class. (That
596 leaves a tidy distinction between the lexicon as the things we
597 know how to I<say>, and the rest of the things in the lexicon class
598 as things that we know how to I<do>.) Consider
599 this example of a processor for responses to French "oui/non"
603 return undef unless defined $_[1] and length $_[1];
604 my $answer = lc $_[1]; # smash case
605 return 1 if $answer eq 'o' or $answer eq 'oui';
606 return 0 if $answer eq 'n' or $answer eq 'non';
610 ...which you'd then call in a construct like this:
613 until(defined $response) {
614 print $lh->maketext("Open the pod bay door (y/n)? ");
615 $response = $lh->y_or_n( get_input_from_keyboard_somehow() );
617 if($response) { $pod_bay_door->open() }
618 else { $pod_bay_door->leave_closed() }
620 Other data worth storing in a lexicon might be things like
621 filenames for language-targetted resources:
625 => "/styles/en_us/main_splash.png",
626 "_main_splash_imagemap"
627 => "/styles/en_us/main_splash.incl",
628 "_general_graphics_path"
631 => "/styles/en_us/hey_there.wav",
635 => "right_arrow.png",
636 # In some other languages, left equals
637 # BACKwards, and right is FOREwards.
640 You might want to do the same thing for expressing key bindings
641 or the like (since hardwiring "q" as the binding for the function
642 that quits a screen/menu/program is useful only if your language
643 happens to associate "q" with "quit"!)
645 =head1 BRACKET NOTATION
647 Bracket Notation is a crucial feature of Locale::Maketext. I mean
648 Bracket Notation to provide a replacement for sprintf formatting.
649 Everything you do with Bracket Notation could be done with a sub block,
650 but bracket notation is meant to be much more concise.
652 Bracket Notation is a like a miniature "template" system (in the sense
653 of L<Text::Template|Text::Template>, not in the sense of C++ templates),
654 where normal text is passed thru basically as is, but text is special
655 regions is specially interpreted. In Bracket Notation, you use brackets
656 ("[...]" -- not "{...}"!) to note sections that are specially interpreted.
658 For example, here all the areas that are taken literally are underlined with
659 a "^", and all the in-bracket special regions are underlined with an X:
661 "Minimum ([_1]) is larger than maximum ([_2])!\n",
662 ^^^^^^^^^ XX ^^^^^^^^^^^^^^^^^^^^^^^^^^ XX ^^^^
664 When that string is compiled from bracket notation into a real Perl sub,
665 it's basically turned into:
673 ") is larger than maximum (",
677 # to be called by $lh->maketext(KEY, params...)
679 In other words, text outside bracket groups is turned into string
680 literals. Text in brackets is rather more complex, and currently follows
687 Bracket groups that are empty, or which consist only of whitespace,
688 are ignored. (Examples: "[]", "[ ]", or a [ and a ] with returns
689 and/or tabs and/or spaces between them.
691 Otherwise, each group is taken to be a comma-separated group of items,
692 and each item is interpreted as follows:
696 An item that is "_I<digits>" or "_-I<digits>" is interpreted as
697 $_[I<value>]. I.e., "_1" is becomes with $_[1], and "_-3" is interpreted
698 as $_[-3] (in which case @_ should have at least three elements in it).
699 Note that $_[0] is the language handle, and is typically not named
704 An item "_*" is interpreted to mean "all of @_ except $_[0]".
705 I.e., C<@_[1..$#_]>. Note that this is an empty list in the case
706 of calls like $lh->maketext(I<key>) where there are no
707 parameters (except $_[0], the language handle).
711 Otherwise, each item is interpreted as a string literal.
715 The group as a whole is interpreted as follows:
721 If the first item in a bracket group looks like a method name,
722 then that group is interpreted like this:
724 $lh->that_method_name(
725 ...rest of items in this group...
730 If the first item in a bracket group is "*", it's taken as shorthand
731 for the so commonly called "quant" method. Similarly, if the first
732 item in a bracket group is "#", it's taken to be shorthand for
737 If the first item in a bracket group is empty-string, or "_*"
738 or "_I<digits>" or "_-I<digits>", then that group is interpreted
739 as just the interpolation of all its items:
742 ...rest of items in this group...
745 Examples: "[_1]" and "[,_1]", which are synonymous; and
746 "[,ID-(,_4,-,_2,)]", which compiles as
747 C<join "", "ID-(", $_[4], "-", $_[2], ")">.
751 Otherwise this bracket group is invalid. For example, in the group
752 "[!@#,whatever]", the first item C<"!@#"> is neither empty-string,
753 "_I<number>", "_-I<number>", "_*", nor a valid method name; and so
754 Locale::Maketext will throw an exception of you try compiling an
755 expression containing this bracket group.
759 Note, incidentally, that items in each group are comma-separated,
760 not C</\s*,\s*/>-separated. That is, you might expect that this
763 "Hoohah [foo, _1 , bar ,baz]!"
765 would compile to this:
771 $lh->foo( $_[1], "bar", "baz"),
775 But it actually compiles as this:
781 $lh->foo(" _1 ", " bar ", "baz"), #!!!
785 In the notation discussed so far, the characters "[" and "]" are given
786 special meaning, for opening and closing bracket groups, and "," has
787 a special meaning inside bracket groups, where it separates items in the
788 group. This begs the question of how you'd express a literal "[" or
789 "]" in a Bracket Notation string, and how you'd express a literal
790 comma inside a bracket group. For this purpose I've adopted "~" (tilde)
791 as an escape character: "~[" means a literal '[' character anywhere
792 in Bracket Notation (i.e., regardless of whether you're in a bracket
793 group or not), and ditto for "~]" meaning a literal ']', and "~," meaning
794 a literal comma. (Altho "," means a literal comma outside of
795 bracket groups -- it's only inside bracket groups that commas are special.)
797 And on the off chance you need a literal tilde in a bracket expression,
798 you get it with "~~".
800 Currently, an unescaped "~" before a character
801 other than a bracket or a comma is taken to mean just a "~" and that
802 charecter. I.e., "~X" means the same as "~~X" -- i.e., one literal tilde,
803 and then one literal "X". However, by using "~X", you are assuming that
804 no future version of Maketext will use "~X" as a magic escape sequence.
805 In practice this is not a great problem, since first off you can just
806 write "~~X" and not worry about it; second off, I doubt I'll add lots
807 of new magic characters to bracket notation; and third off, you
808 aren't likely to want literal "~" characters in your messages anyway,
809 since it's not a character with wide use in natural language text.
811 Brackets must be balanced -- every openbracket must have
812 one matching closebracket, and vice versa. So these are all B<invalid>:
814 "I ate [quant,_1,rhubarb pie."
815 "I ate [quant,_1,rhubarb pie[."
816 "I ate quant,_1,rhubarb pie]."
817 "I ate quant,_1,rhubarb pie[."
819 Currently, bracket groups do not nest. That is, you B<cannot> say:
821 "Foo [bar,baz,[quux,quuux]]\n";
823 If you need a notation that's that powerful, use normal Perl:
831 $lh->bar('baz', $lh->quux('quuux')),
837 Or write the "bar" method so you don't need to pass it the
838 output from calling quux.
840 I do not anticipate that you will need (or particularly want)
841 to nest bracket groups, but you are welcome to email me with
842 convincing (real-life) arguments to the contrary.
846 If maketext goes to look in an individual %Lexicon for an entry
847 for I<key> (where I<key> does not start with an underscore), and
848 sees none, B<but does see> an entry of "_AUTO" => I<some_true_value>,
849 then we actually define $Lexicon{I<key>} = I<key> right then and there,
850 and then use that value as if it had been there all
851 along. This happens before we even look in any superclass %Lexicons!
853 (This is meant to be somewhat like the AUTOLOAD mechanism in
854 Perl's function call system -- or, looked at another way,
855 like the L<AutoLoader|AutoLoader> module.)
857 I can picture all sorts of circumstances where you just
858 do not want lookup to be able to fail (since failing
859 normally means that maketext throws a C<die>, altho
860 see the next section for greater control over that). But
861 here's one circumstance where _AUTO lexicons are meant to
862 be I<especially> useful:
864 As you're writing an application, you decide as you go what messages
865 you need to emit. Normally you'd go to write this:
868 go_process_file($filename)
870 print "Couldn't find file \"$filename\"!\n";
873 but since you anticipate localizing this, you write:
875 use ThisProject::I18N;
876 my $lh = ThisProject::I18N->get_handle();
877 # For the moment, assume that things are set up so
878 # that we load class ThisProject::I18N::en
879 # and that that's the class that $lh belongs to.
882 go_process_file($filename)
885 "Couldn't find file \"[_1]\"!\n", $filename
889 Now, right after you've just written the above lines, you'd
890 normally have to go open the file
891 ThisProject/I18N/en.pm, and immediately add an entry:
893 "Couldn't find file \"[_1]\"!\n"
894 => "Couldn't find file \"[_1]\"!\n",
896 But I consider that somewhat of a distraction from the work
897 of getting the main code working -- to say nothing of the fact
898 that I often have to play with the program a few times before
899 I can decide exactly what wording I want in the messages (which
900 in this case would require me to go changing three lines of code:
901 the call to maketext with that key, and then the two lines in
902 ThisProject/I18N/en.pm).
904 However, if you set "_AUTO => 1" in the %Lexicon in,
905 ThisProject/I18N/en.pm (assuming that English (en) is
906 the language that all your programmers will be using for this
907 project's internal message keys), then you don't ever have to
908 go adding lines like this
910 "Couldn't find file \"[_1]\"!\n"
911 => "Couldn't find file \"[_1]\"!\n",
913 to ThisProject/I18N/en.pm, because if _AUTO is true there,
914 then just looking for an entry with the key "Couldn't find
915 file \"[_1]\"!\n" in that lexicon will cause it to be added,
918 Note that the reason that keys that start with "_"
919 are immune to _AUTO isn't anything generally magical about
920 the underscore character -- I just wanted a way to have most
921 lexicon keys be autoable, except for possibly a few, and I
922 arbitrarily decided to use a leading underscore as a signal
923 to distinguish those few.
925 =head1 CONTROLLING LOOKUP FAILURE
927 If you call $lh->maketext(I<key>, ...parameters...),
928 and there's no entry I<key> in $lh's class's %Lexicon, nor
929 in the superclass %Lexicon hash, I<and> if we can't auto-make
930 I<key> (because either it starts with a "_", or because none
931 of its lexicons have C<_AUTO =E<gt> 1,>), then we have
932 failed to find a normal way to maketext I<key>. What then
933 happens in these failure conditions, depends on the $lh object
936 If the language handle has no "fail" attribute, maketext
937 will simply throw an exception (i.e., it calls C<die>, mentioning
938 the I<key> whose lookup failed, and naming the line number where
939 the calling $lh->maketext(I<key>,...) was.
941 If the language handle has a "fail" attribute whose value is a
942 coderef, then $lh->maketext(I<key>,...params...) gives up and calls:
944 return &{$that_subref}($lh, $key, @params);
946 Otherwise, the "fail" attribute's value should be a string denoting
947 a method name, so that $lh->maketext(I<key>,...params...) can
950 return $lh->$that_method_name($phrase, @params);
952 The "fail" attribute can be accessed with the C<fail_with> method:
955 $lh->fail_with( \&failure_handler );
957 # Set to a method name:
958 $lh->fail_with( 'failure_method' );
960 # Set to nothing (i.e., so failure throws a plain exception)
961 $lh->fail_with( undef );
964 $handler = $lh->fail_with();
966 Now, as to what you may want to do with these handlers: Maybe you'd
967 want to log what key failed for what class, and then die. Maybe
968 you don't like C<die> and instead you want to send the error message
969 to STDOUT (or wherever) and then merely C<exit()>.
971 Or maybe you don't want to C<die> at all! Maybe you could use a
974 # Make all lookups fall back onto an English value,
975 # but after we log it for later fingerpointing.
976 my $lh_backup = ThisProject->get_handle('en');
977 open(LEX_FAIL_LOG, ">>wherever/lex.log") || die "GNAARGH $!";
979 my($failing_lh, $key, $params) = @_;
980 print LEX_FAIL_LOG scalar(localtime), "\t",
981 ref($failing_lh), "\t", $key, "\n";
982 return $lh_backup->maketext($key,@params);
985 Some users have expressed that they think this whole mechanism of
986 having a "fail" attribute at all, seems a rather pointless complication.
987 But I want Locale::Maketext to be usable for software projects of I<any>
988 scale and type; and different software projects have different ideas
989 of what the right thing is to do in failure conditions. I could simply
990 say that failure always throws an exception, and that if you want to be
991 careful, you'll just have to wrap every call to $lh->maketext in an
992 S<eval { }>. However, I want programmers to reserve the right (via
993 the "fail" attribute) to treat lookup failure as something other than
994 an exception of the same level of severity as a config file being
995 unreadable, or some essential resource being inaccessable.
997 One possibly useful value for the "fail" attribute is the method name
998 "failure_handler_auto". This is a method defined in class
999 Locale::Maketext itself. You set it with:
1001 $lh->fail_with('failure_handler_auto');
1003 Then when you call $lh->maketext(I<key>, ...parameters...) and
1004 there's no I<key> in any of those lexicons, maketext gives up with
1006 return $lh->failure_handler_auto($key, @params);
1008 But failure_handler_auto, instead of dying or anything, compiles
1009 $key, caching it in $lh->{'failure_lex'}{$key} = $complied,
1010 and then calls the compiled value, and returns that. (I.e., if
1011 $key looks like bracket notation, $compiled is a sub, and we return
1012 &{$compiled}(@params); but if $key is just a plain string, we just
1015 The effect of using "failure_auto_handler"
1016 is like an AUTO lexicon, except that it 1) compiles $key even if
1017 it starts with "_", and 2) you have a record in the new hashref
1018 $lh->{'failure_lex'} of all the keys that have failed for
1019 this object. This should avoid your program dying -- as long
1020 as your keys aren't actually invalid as bracket code, and as
1021 long as they don't try calling methods that don't exist.
1023 "failure_auto_handler" may not be exactly what you want, but I
1024 hope it at least shows you that maketext failure can be mitigated
1025 in any number of very flexible ways. If you can formalize exactly
1026 what you want, you should be able to express that as a failure
1027 handler. You can even make it default for every object of a given
1028 class, by setting it in that class's init:
1031 my $lh = $_[0]; # a newborn handle
1033 $lh->fail_with('my_clever_failure_handler');
1036 sub my_clever_failure_handler {
1037 ...you clever things here...
1040 =head1 HOW TO USE MAKETEXT
1042 Here is a brief checklist on how to use Maketext to localize
1049 Decide what system you'll use for lexicon keys. If you insist,
1050 you can use opaque IDs (if you're nostalgic for C<catgets>),
1051 but I have better suggestions in the
1052 section "Entries in Each Lexicon", above. Assuming you opt for
1053 meaningful keys that double as values (like "Minimum ([_1]) is
1054 larger than maximum ([_2])!\n"), you'll have to settle on what
1055 language those should be in. For the sake of argument, I'll
1056 call this English, specifically American English, "en-US".
1060 Create a class for your localization project. This is
1061 the name of the class that you'll use in the idiom:
1064 my $lh = Projname::L10N->get_handle(...) || die "Language?";
1066 Assuming your call your class Projname::L10N, create a class
1067 consisting minimally of:
1069 package Projname::L10N;
1070 use base qw(Locale::Maketext);
1071 ...any methods you might want all your languages to share...
1073 # And, assuming you want the base class to be an _AUTO lexicon,
1074 # as is discussed a few sections up:
1080 Create a class for the language your internal keys are in. Name
1081 the class after the language-tag for that language, in lowercase,
1082 with dashes changed to underscores. Assuming your project's first
1083 language is US English, you should call this Projname::L10N::en_us.
1084 It should consist minimally of:
1086 package Projname::L10N::en_us;
1087 use base qw(Projname::L10N);
1093 (For the rest of this section, I'll assume that this "first
1094 language class" of Projname::L10N::en_us has
1099 Go and write your program. Everywhere in your program where
1102 print "Foobar $thing stuff\n";
1104 instead do it thru maketext, using no variable interpolation in
1107 print $lh->maketext("Foobar [_1] stuff\n", $thing);
1109 If you get tired of constantly saying C<print $lh-E<gt>maketext>,
1110 consider making a functional wrapper for it, like so:
1114 $lh = Projname::L10N->get_handle(...) || die "Language?";
1115 sub pmt (@) { print( $lh->maketext(@_)) }
1116 # "pmt" is short for "Print MakeText"
1118 # so if maketext fails, we see made the call to pmt
1120 Besides whole phrases meant for output, anything language-dependent
1121 should be put into the class Projname::L10N::en_us,
1122 whether as methods, or as lexicon entries -- this is discussed
1123 in the section "Entries in Each Lexicon", above.
1127 Once the program is otherwise done, and once its localization for
1128 the first language works right (via the data and methods in
1129 Projname::L10N::en_us), you can get together the data for translation.
1130 If your first language lexicon isn't an _AUTO lexicon, then you already
1131 have all the messages explicitly in the lexicon (or else you'd be
1132 getting exceptions thrown when you call $lh->maketext to get
1133 messages that aren't in there). But if you were (advisedly) lazy and are
1134 using an _AUTO lexicon, then you've got to make a list of all the phrases
1135 that you've so far been letting _AUTO generate for you. There are very
1136 many ways to assemble such a list. The most straightforward is to simply
1137 grep the source for every occurrence of "maketext" (or calls
1138 to wrappers around it, like the above C<pmt> function), and to log the
1143 You may at this point want to consider whether the your base class
1144 (Projname::L10N) that all lexicons inherit from (Projname::L10N::en,
1145 Projname::L10N::es, etc.) should be an _AUTO lexicon. It may be true
1146 that in theory, all needed messages will be in each language class;
1147 but in the presumably unlikely or "impossible" case of lookup failure,
1148 you should consider whether your program should throw an exception,
1149 emit text in English (or whatever your project's first language is),
1150 or some more complex solution as described in the section
1151 "Controlling Lookup Failure", above.
1155 Submit all messages/phrases/etc. to translators.
1157 (You may, in fact, want to start with localizing to I<one> other language
1158 at first, if you're not sure that you've property abstracted the
1159 language-dependent parts of your code.)
1161 Translators may request clarification of the situation in which a
1162 particular phrase is found. For example, in English we are entirely happy
1163 saying "I<n> files found", regardless of whether we mean "I looked for files,
1164 and found I<n> of them" or the rather distinct situation of "I looked for
1165 something else (like lines in files), and along the way I saw I<n>
1166 files." This may involve rethinking things that you thought quite clear:
1167 should "Edit" on a toolbar be a noun ("editing") or a verb ("to edit")? Is
1168 there already a conventionalized way to express that menu option, separate
1169 from the target language's normal word for "to edit"?
1171 In all cases where the very common phenomenon of quantification
1172 (saying "I<N> files", for B<any> value of N)
1173 is involved, each translator should make clear what dependencies the
1174 number causes in the sentence. In many cases, dependency is
1175 limited to words adjacent to the number, in places where you might
1176 expect them ("I found the-?PLURAL I<N>
1177 empty-?PLURAL directory-?PLURAL"), but in some cases there are
1178 unexpected dependencies ("I found-?PLURAL ..."!) as well as long-distance
1179 dependencies "The I<N> directory-?PLURAL could not be deleted-?PLURAL"!).
1181 Remind the translators to consider the case where N is 0:
1182 "0 files found" isn't exactly natural-sounding in any language, but it
1183 may be unacceptable in many -- or it may condition special
1184 kinds of agreement (similar to English "I didN'T find ANY files").
1186 Remember to ask your translators about numeral formatting in their
1187 language, so that you can override the C<numf> method as
1188 appropriate. Typical variables in number formatting are: what to
1189 use as a decimal point (comma? period?); what to use as a thousands
1190 separator (space? nonbreakinng space? comma? period? small
1191 middot? prime? apostrophe?); and even whether the so-called "thousands
1192 separator" is actually for every third digit -- I've heard reports of
1193 two hundred thousand being expressable as "2,00,000" for some Indian
1194 (Subcontinental) languages, besides the less surprising "S<200 000>",
1195 "200.000", "200,000", and "200'000". Also, using a set of numeral
1196 glyphs other than the usual ASCII "0"-"9" might be appreciated, as via
1197 C<tr/0-9/\x{0966}-\x{096F}/> for getting digits in Devanagari script
1198 (for Hindi, Konkani, others).
1200 The basic C<quant> method that Locale::Maketext provides should be
1201 good for many languages. For some languages, it might be useful
1202 to modify it (or its constituent C<numerate> method)
1203 to take a plural form in the two-argument call to C<quant>
1204 (as in "[quant,_1,files]") if
1205 it's all-around easier to infer the singular form from the plural, than
1206 to infer the plural form from the singular.
1208 But for other languages (as is discussed at length
1209 in L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>), simple
1210 C<quant>/C<numerify> is not enough. For the particularly problematic
1211 Slavic languages, what you may need is a method which you provide
1212 with the number, the citation form of the noun to quantify, and
1213 the case and gender that the sentence's syntax projects onto that
1214 noun slot. The method would then be responsible for determining
1215 what grammatical number that numeral projects onto its noun phrase,
1216 and what case and gender it may override the normal case and gender
1217 with; and then it would look up the noun in a lexicon providing
1218 all needed inflected forms.
1222 You may also wish to discuss with the translators the question of
1223 how to relate different subforms of the same language tag,
1224 considering how this reacts with C<get_handle>'s treatment of
1225 these. For example, if a user accepts interfaces in "en, fr", and
1226 you have interfaces available in "en-US" and "fr", what should
1227 they get? You may wish to resolve this by establishing that "en"
1228 and "en-US" are effectively synonymous, by having one class
1229 zero-derive from the other.
1231 For some languages this issue may never come up (Danish is rarely
1232 expressed as "da-DK", but instead is just "da"). And for other
1233 languages, the whole concept of a "generic" form may verge on
1234 being uselessly vague, particularly for interfaces involving voice
1235 media in forms of Arabic or Chinese.
1239 Once you've localized your program/site/etc. for all desired
1240 languages, be sure to show the result (whether live, or via
1241 screenshots) to the translators. Once they approve, make every
1242 effort to have it then checked by at least one other speaker of
1243 that language. This holds true even when (or especially when) the
1244 translation is done by one of your own programmers. Some
1245 kinds of systems may be harder to find testers for than others,
1246 depending on the amount of domain-specific jargon and concepts
1247 involved -- it's easier to find people who can tell you whether
1248 they approve of your translation for "delete this message" in an
1249 email-via-Web interface, than to find people who can give you
1250 an informed opinion on your translation for "attribute value"
1251 in an XML query tool's interface.
1257 I recommend reading all of these:
1259 L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13> -- my I<The Perl
1260 Journal> article about Maketext. It explains many important concepts
1261 underlying Locale::Maketext's design, and some insight into why
1262 Maketext is better than the plain old approach of just having
1263 message catalogs that are just databases of sprintf formats.
1265 L<File::Findgrep|File::Findgrep> is a sample application/module
1266 that uses Locale::Maketext to localize its messages.
1268 L<I18N::LangTags|I18N::LangTags>.
1270 L<Win32::Locale|Win32::Locale>.
1272 RFC 3066, I<Tags for the Identification of Languages>,
1273 as at http://sunsite.dk/RFC/rfc/rfc3066.html
1275 RFC 2277, I<IETF Policy on Character Sets and Languages>
1276 is at http://sunsite.dk/RFC/rfc/rfc2277.html -- much of it is
1277 just things of interest to protocol designers, but it explains
1278 some basic concepts, like the distinction between locales and
1281 The manual for GNU C<gettext>. The gettext dist is available in
1282 C<ftp://prep.ai.mit.edu/pub/gnu/> -- get
1283 a recent gettext tarball and look in its "doc/" directory, there's
1284 an easily browsable HTML version in there. The
1285 gettext documentation asks lots of questions worth thinking
1286 about, even if some of their answers are sometimes wonky,
1287 particularly where they start talking about pluralization.
1289 The Locale/Maketext.pm source. Obverse that the module is much
1290 shorter than its documentation!
1292 =head1 COPYRIGHT AND DISCLAIMER
1294 Copyright (c) 1999-2001 Sean M. Burke. All rights reserved.
1296 This library is free software; you can redistribute it and/or modify
1297 it under the same terms as Perl itself.
1299 This program is distributed in the hope that it will be useful, but
1300 without any warranty; without even the implied warranty of
1301 merchantability or fitness for a particular purpose.
1305 Sean M. Burke C<sburke@cpan.org>