mingw/html/lib/Locale/Maketext.html

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