maketext.pod

1. 记录每个帖子的访问人情况

as this pseudocode describes:

     if $number is 0 and there's a $negative,
        return $negative;
     elsif $number is 1,
        return "1 $singular";
     elsif there's a $plural,
        return "$number $plural";
     else
        return "$number " . $singular . "s";
     #
     # ...except that we actually call numf to
     #  stringify $number before returning it.

So for English (with Bracket Notation)
C<"...[quant,_1,file]..."> is fine (for 0 it returns "0 files",
for 1 it returns "1 file", and for more it returns "2 files", etc.)

But for "directory", you'd want C<"[quant,_1,direcory,directories]">
so that our elementary C<quant> method doesn't think that the
plural of "directory" is "directorys".  And you might find that the
output may sound better if you specify a negative form, as in:

     "[quant,_1,file,files,No files] matched your query.\n"

Remember to keep in mind verb agreement (or adjectives too, in
other languages), as in:

     "[quant,_1,document] were matched.\n"

Because if _1 is one, you get "1 document B<were> matched".
An acceptable hack here is to do something like this:

     "[quant,_1,document was, documents were] matched.\n"

=item $language->numf($number)

This returns the given number formatted nicely according to
this language's conventions.  Maketext's default method is
mostly to just take the normal string form of the number
(applying sprintf "%G" for only very large numbers), and then
to add commas as necessary.  (Except that
we apply C<tr/,./.,/> if $language->{'numf_comma'} is true;
that's a bit of a hack that's useful for languages that express
two million as "2.000.000" and not as "2,000,000").

If you want anything fancier, consider overriding this with something
that uses L<Number::Format|Number::Format>, or does something else
entirely.

Note that numf is called by quant for stringifying all quantifying
numbers.

=item $language->sprintf($format, @items)

This is just a wrapper around Perl's normal C<sprintf> function.
It's provided so that you can use "sprintf" in Bracket Notation:

     "Couldn't access datanode [sprintf,%10x=~[%s~],_1,_2]!\n"

returning...

     Couldn't access datanode      Stuff=[thangamabob]!

=item $language->language_tag()

Currently this just takes the last bit of C<ref($language)>, turns
underscores to dashes, and returns it.  So if $language is
an object of class Hee::HOO::Haw::en_us, $language->language_tag()
returns "en-us".  (Yes, the usual representation for that language
tag is "en-US", but case is I<never> considered meaningful in
language-tag comparison.)

You may override this as you like; Maketext doesn't use it for
anything.

=item $language->encoding()

Currently this isn't used for anything, but it's provided
(with default value of
C<(ref($language) && $language-E<gt>{'encoding'})) or "iso-8859-1">
) as a sort of suggestion that it may be useful/necessary to
associate encodings with your language handles (whether on a
per-class or even per-handle basis.)

=back

=head2 Language Handle Attributes and Internals

A language handle is a flyweight object -- i.e., it doesn't (necessarily)
carry any data of interest, other than just being a member of
whatever class it belongs to.

A language handle is implemented as a blessed hash.  Subclasses of yours
can store whatever data you want in the hash.  Currently the only hash
entry used by any crucial Maketext method is "fail", so feel free to
use anything else as you like.

B<Remember: Don't be afraid to read the Maketext source if there's
any point on which this documentation is unclear.>  This documentation
is vastly longer than the module source itself.

=over

=back

=head1 LANGUAGE CLASS HIERARCHIES

These are Locale::Maketext's assumptions about the class
hierarchy formed by all your language classes:

=over

=item *

You must have a project base class, which you load, and
which you then use as the first argument in
the call to YourProjClass->get_handle(...).  It should derive
(whether directly or indirectly) from Locale::Maketext.
It B<doesn't matter> how you name this class, altho assuming this
is the localization component of your Super Mega Program,
good names for your project class might be
SuperMegaProgram::Localization, SuperMegaProgram::L10N,
SuperMegaProgram::I18N, SuperMegaProgram::International,
or even SuperMegaProgram::Languages or SuperMegaProgram::Messages.

=item *

Language classes are what YourProjClass->get_handle will try to load.
It will look for them by taking each language-tag (B<skipping> it
if it doesn't look like a language-tag or locale-tag!), turning it to
all lowercase, turning and dashes to underscores, and appending it
to YourProjClass . "::".  So this:

  $lh = YourProjClass->get_handle(
    'en-US', 'fr', 'kon', 'i-klingon', 'i-klingon-romanized'
  );

will try loading the classes 
YourProjClass::en_us (note lowercase!), YourProjClass::fr, 
YourProjClass::kon,
YourProjClass::i_klingon
and YourProjClass::i_klingon_romanized.  (And it'll stop at the
first one that actually loads.)

=item *

I assume that each language class derives (directly or indirectly)
from your project class, and also defines its @ISA, its %Lexicon,
or both.  But I anticipate no dire consequences if these assumptions
do not hold.

=item *

Language classes may derive from other language classes (altho they
should have "use I<Thatclassname>" or "use base qw(I<...classes...>)").
They may derive from the project
class.  They may derive from some other class altogether.  Or via
multiple inheritance, it may derive from any mixture of these.

=item *

I foresee no problems with having multiple inheritance in
your hierarchy of language classes.  (As usual, however, Perl will
complain bitterly if you have a cycle in the hierarchy: i.e., if
any class is its own ancestor.)

=back

=head1 ENTRIES IN EACH LEXICON

A typical %Lexicon entry is meant to signify a phrase,
taking some number (0 or more) of parameters.  An entry
is meant to be accessed by via
a string I<key> in $lh->maketext(I<key>, ...parameters...),
which should return a string that is generally meant for
be used for "output" to the user -- regardless of whether
this actually means printing to STDOUT, writing to a file,
or putting into a GUI widget.

While the key must be a string value (since that's a basic
restriction that Perl places on hash keys), the value in
the lexicon can currenly be of several types:
a defined scalar, scalarref, or coderef.  The use of these is
explained above, in the section 'The "maketext" Method', and
Bracket Notation for strings is discussed in the next section.

While you can use arbitrary unique IDs for lexicon keys
(like "_min_larger_max_error"), it is often
useful for if an entry's key is itself a valid value, like
this example error message:

  "Minimum ([_1]) is larger than maximum ([_2])!\n",

Compare this code that uses an arbitrary ID...

  die $lh->maketext( "_min_larger_max_error", $min, $max )
   if $min > $max;

...to this code that uses a key-as-value:

  die $lh->maketext(
   "Minimum ([_1]) is larger than maximum ([_2])!\n",
   $min, $max
  ) if $min > $max;

The second is, in short, more readable.  In particular, it's obvious
that the number of parameters you're feeding to that phrase (two) is
the number of parameters that it I<wants> to be fed.  (Since you see
_1 and a _2 being used in the key there.)

Also, once a project is otherwise
complete and you start to localize it, you can scrape together
all the various keys you use, and pass it to a translator; and then
the translator's work will go faster if what he's presented is this:

 "Minimum ([_1]) is larger than maximum ([_2])!\n",
  => "",   # fill in something here, Jacques!

rather than this more cryptic mess:

 "_min_larger_max_error"
  => "",   # fill in something here, Jacques

I think that keys as lexicon values makes the completed lexicon
entries more readable:

 "Minimum ([_1]) is larger than maximum ([_2])!\n",
  => "Le minimum ([_1]) est plus grand que le maximum ([_2])!\n",

Also, having valid values as keys becomes very useful if you set
up an _AUTO lexicon.  _AUTO lexicons are discussed in a later
section.

I almost always use keys that are themselves
valid lexicon values.  One notable exception is when the value is
quite long.  For example, to get the screenful of data that
a command-line program might returns when given an unknown switch,
I often just use a key "_USAGE_MESSAGE".  At that point I then go
and immediately to define that lexicon entry in the
ProjectClass::L10N::en lexicon (since English is always my "project
lanuage"):

  '_USAGE_MESSAGE' => <<'EOSTUFF',
  ...long long message...
  EOSTUFF

and then I can use it as:

  getopt('oDI', \%opts) or die $lh->maketext('_USAGE_MESSAGE');

Incidentally,
note that each class's C<%Lexicon> inherits-and-extends
the lexicons in its superclasses.  This is not because these are
special hashes I<per se>, but because you access them via the
C<maketext> method, which looks for entries across all the
C<%Lexicon>'s in a language class I<and> all its ancestor classes.
(This is because the idea of "class data" isn't directly implemented
in Perl, but is instead left to individual class-systems to implement
as they see fit..)

Note that you may have things stored in a lexicon
besides just phrases for output:  for example, if your program
takes input from the keyboard, asking a "(Y/N)" question,
you probably need to know what equivalent of "Y[es]/N[o]" is
in whatever language.  You probably also need to know what
the equivalents of the answers "y" and "n" are.  You can
store that information in the lexicon (say, under the keys
"~answer_y" and "~answer_n", and the long forms as
"~answer_yes" and "~answer_no", where "~" is just an ad-hoc
character meant to indicate to programmers/translators that
these are not phrases for output).

Or instead of storing this in the language class's lexicon,
you can (and, in some cases, really should) represent the same bit
of knowledge as code is a method in the language class.  (That
leaves a tidy distinction between the lexicon as the things we
know how to I<say>, and the rest of the things in the lexicon class
as things that we know how to I<do>.)  Consider
this example of a processor for responses to French "oui/non"
questions:

  sub y_or_n {
    return undef unless defined $_[1] and length $_[1];
    my $answer = lc $_[1];  # smash case
    return 1 if $answer eq 'o' or $answer eq 'oui';
    return 0 if $answer eq 'n' or $answer eq 'non';
    return undef;
  }

...which you'd then call in a construct like this:

  my $response;
  until(defined $response) {
    print $lh->maketext("Open the pod bay door (y/n)? ");
    $response = $lh->y_or_n( get_input_from_keyboard_somehow() );
  }
  if($response) { $pod_bay_door->open()         }
  else          { $pod_bay_door->leave_closed() }

Other data worth storing in a lexicon might be things like
filenames for language-targetted resources:

  ...
  "_main_splash_png"
    => "/styles/en_us/main_splash.png",
  "_main_splash_imagemap"
    => "/styles/en_us/main_splash.incl",
  "_general_graphics_path"
    => "/styles/en_us/",
  "_alert_sound"
    => "/styles/en_us/hey_there.wav",
  "_forward_icon"
   => "left_arrow.png",
  "_backward_icon"
   => "right_arrow.png",
  # In some other languages, left equals
  #  BACKwards, and right is FOREwards.
  ...

You might want to do the same thing for expressing key bindings
or the like (since hardwiring "q" as the binding for the function
that quits a screen/menu/program is useful only if your language
happens to associate "q" with "quit"!)

=head1 BRACKET NOTATION

Bracket Notation is a crucial feature of Locale::Maketext.  I mean
Bracket Notation to provide a replacement for sprintf formatting.
Everything you do with Bracket Notation could be done with a sub block,
but bracket notation is meant to be much more concise.