maketext.pod

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

# Time-stamp: "2001-06-21 23:12:39 MDT"

=head1 NAME

Locale::Maketext -- framework for localization

=head1 SYNOPSIS

  package MyProgram;
  use strict;
  use MyProgram::L10N;
   # ...which inherits from Locale::Maketext
  my $lh = MyProgram::L10N->get_handle() || die "What language?";
  ...
  # And then any messages your program emits, like:
  warn $lh->maketext( "Can't open file [_1]: [_2]\n", $f, $! );
  ...

=head1 DESCRIPTION

It is a common feature of applications (whether run directly,
or via the Web) for them to be "localized" -- i.e., for them
to a present an English interface to an English-speaker, a German
interface to a German-speaker, and so on for all languages it's
programmed with.  Locale::Maketext
is a framework for software localization; it provides you with the
tools for organizing and accessing the bits of text and text-processing
code that you need for producing localized applications.

In order to make sense of Maketext and how all its
components fit together, you should probably
go read L<Locale::Maketext::TPJ13|Locale::Maketext::TPJ13>, and
I<then> read the following documentation.

You may also want to read over the source for C<File::Findgrep>
and its constituent modules -- they are a complete (if small)
example application that uses Maketext.

=head1 QUICK OVERVIEW

The basic design of Locale::Maketext is object-oriented, and
Locale::Maketext is an abstract base class, from which you
derive a "project class".
The project class (with a name like "TkBocciBall::Localize",
which you then use in your module) is in turn the base class
for all the "language classes" for your project
(with names "TkBocciBall::Localize::it", 
"TkBocciBall::Localize::en",
"TkBocciBall::Localize::fr", etc.).

A language class is
a class containing a lexicon of phrases as class data,
and possibly also some methods that are of use in interpreting
phrases in the lexicon, or otherwise dealing with text in that
language.

An object belonging to a language class is called a "language
handle"; it's typically a flyweight object.

The normal course of action is to call:

  use TkBocciBall::Localize;  # the localization project class
  $lh = TkBocciBall::Localize->get_handle();
   # Depending on the user's locale, etc., this will
   # make a language handle from among the classes available,
   # and any defaults that you declare.
  die "Couldn't make a language handle??" unless $lh;

From then on, you use the C<maketext> function to access
entries in whatever lexicon(s) belong to the language handle
you got.  So, this:

  print $lh->maketext("You won!"), "\n";

...emits the right text for this language.  If the object
in C<$lh> belongs to class "TkBocciBall::Localize::fr" and
%TkBocciBall::Localize::fr::Lexicon contains C<("You won!"
=E<gt> "Tu as gagnE<eacute>!")>, then the above
code happily tells the user "Tu as gagnE<eacute>!".

=head1 METHODS

Locale::Maketext offers a variety of methods, which fall
into three categories:

=over

=item *

Methods to do with constructing language handles.

=item *

C<maketext> and other methods to do with accessing %Lexicon data
for a given language handle.

=item *

Methods that you may find it handy to use, from routines of
yours that you put in %Lexicon entries.

=back

These are covered in the following section.

=head2 Construction Methods

These are to do with constructing a language handle:

=over

=item *

$lh = YourProjClass->get_handle( ...langtags... ) || die "lg-handle?";

This tries loading classes based on the language-tags you give (like
C<("en-US", "sk", "kon", "es-MX", "ja", "i-klingon")>, and for the first class
that succeeds, returns YourProjClass::I<language>->new().

It runs thru the entire given list of language-tags, and finds no classes
for those exact terms, it then tries "superordinate" language classes.
So if no "en-US" class (i.e., YourProjClass::en_us)
was found, nor classes for anything else in that list, we then try
its superordinate, "en" (i.e., YourProjClass::en), and so on thru 
the other language-tags in the given list: "es".
(The other language-tags in our example list: 
happen to have no superordinates.)

If none of those language-tags leads to loadable classes, we then
try classes derived from YourProjClass->fallback_languages() and
then if nothing comes of that, we use classes named by
YourProjClass->fallback_language_classes().  Then in the (probably
quite unlikely) event that that fails, we just return undef.

=item *

$lh = YourProjClass->get_handleB<()> || die "lg-handle?";

When C<get_handle> is called with an empty parameter list, magic happens:

If C<get_handle> senses that it's running in program that was
invoked as a CGI, then it tries to get language-tags out of the
environment variable "HTTP_ACCEPT_LANGUAGE", and it pretends that
those were the languages passed as parameters to C<get_handle>.

Otherwise (i.e., if not a CGI), this tries various OS-specific ways
to get the language-tags for the current locale/language, and then
pretends that those were the value(s) passed to C<cet_handle>.

Currently this OS-specific stuff consists of looking in the environment
variables "LANG" and "LANGUAGE"; and on MSWin machines (where those
variables are typically unused), this also tries using
the module Win32::Locale to get a language-tag for whatever language/locale
is currently selected in the "Regional Settings" (or "International"?)
Control Panel.  I welcome further
suggestions for making this do the Right Thing under other operating
systems that support localization.

If you're using localization in an application that keeps a configuration
file, you might consider something like this in your project class:

  sub get_handle_via_config {
    my $class = $_[0];
    my $preferred_language = $Config_settings{'language'};
    my $lh;
    if($preferred_language) {
      $lh = $class->get_handle($chosen_language)
       || die "No language handle for \"$chosen_language\" or the like";
    } else {
      # Config file missing, maybe?
      $lh = $class->get_handle()
       || die "Can't get a language handle";
    }
    return $lh;
  }

=item *

$lh = YourProjClass::langname->new();

This constructs a language handle.  You usually B<don't> call this
directly, but instead let C<get_handle> find a language class to C<use>
and to then call ->new on.

=item *

$lh->init();

This is called by ->new to initialize newly-constructed language handles.
If you define an init method in your class, remember that it's usually
considered a good idea to call $lh->SUPER::init in it (presumably at the
beginning), so that all classes get a chance to initialize a new object
however they see fit.

=item *

YourProjClass->fallback_languages()

C<get_handle> appends the return value of this to the end of
whatever list of languages you pass C<get_handle>.  Unless
you override this method, your project class
will inherit Locale::Maketext's C<fallback_languages>, which
currently returns C<('i-default', 'en', 'en-US')>.
("i-default" is defined in RFC 2277).

This method (by having it return the name
of a language-tag that has an existing language class)
can be used for making sure that
C<get_handle> will always manage to construct a language
handle (assuming your language classes are in an appropriate
@INC directory).  Or you can use the next method:

=item *

YourProjClass->fallback_language_classes()

C<get_handle> appends the return value of this to the end
of the list of classes it will try using.  Unless
you override this method, your project class
will inherit Locale::Maketext's C<fallback_language_classes>,
which currently returns an empty list, C<()>.
By setting this to some value (namely, the name of a loadable
language class), you can be sure that
C<get_handle> will always manage to construct a language
handle.

=back

=head2 The "maketext" Method

This is the most important method in Locale::Maketext:

$text = $lh->maketext(I<key>, ...parameters for this phrase...);

This looks in the %Lexicon of the language handle
$lh and all its superclasses, looking
for an entry whose key is the string I<key>.  Assuming such
an entry is found, various things then happen, depending on the
value found:

If the value is a scalarref, the scalar is dereferenced and returned
(and any parameters are ignored).
If the value is a coderef, we return &$value($lh, ...parameters...).
If the value is a string that I<doesn't> look like it's in Bracket Notation,
we return it (after replacing it with a scalarref, in its %Lexicon).
If the value I<does> look like it's in Bracket Notation, then we compile
it into a sub, replace the string in the %Lexicon with the new coderef,
and then we return &$new_sub($lh, ...parameters...).

Bracket Notation is discussed in a later section.  Note
that trying to compile a string into Bracket Notation can throw
an exception if the string is not syntactically valid (say, by not
balancing brackets right.)

Also, calling &$coderef($lh, ...parameters...) can throw any sort of
exception (if, say, code in that sub tries to divide by zero).  But
a very common exception occurs when you have Bracket
Notation text that says to call a method "foo", but there is no such
method.  (E.g., "You have [quaB<tn>,_1,ball]." will throw an exception
on trying to call $lh->quaB<tn>($_[1],'ball') -- you presumably meant
"quant".)  C<maketext> catches these exceptions, but only to make the
error message more readable, at which point it rethrows the exception.

An exception I<may> be thrown if I<key> is not found in any
of $lh's %Lexicon hashes.  What happens if a key is not found,
is discussed in a later section, "Controlling Lookup Failure".

Note that you might find it useful in some cases to override
the C<maketext> method with an "after method", if you want to
translate encodings, or even scripts:

    package YrProj::zh_cn; # Chinese with PRC-style glyphs
    use base ('YrProj::zh_tw');  # Taiwan-style
    sub maketext {
      my $self = shift(@_);
      my $value = $self->maketext(@_);
      return Chineeze::taiwan2mainland($value);
    }

Or you may want to override it with something that traps
any exceptions, if that's critical to your program:

  sub maketext {
    my($lh, @stuff) = @_;
    my $out;
    eval { $out = $lh->SUPER::maketext(@stuff) };
    return $out unless $@;
    ...otherwise deal with the exception...
  }

Other than those two situations, I don't imagine that
it's useful to override the C<maketext> method.  (If
you run into a situation where it is useful, I'd be
interested in hearing about it.)

=over

=item $lh->fail_with I<or> $lh->fail_with(I<PARAM>)

=item $lh->failure_handler_auto

These two methods are discussed in the section "Controlling
Lookup Failure".

=back

=head2 Utility Methods

These are methods that you may find it handy to use, generally
from %Lexicon routines of yours (whether expressed as
Bracket Notation or not).

=over

=item $language->quant($number, $singular)

=item $language->quant($number, $singular, $plural)

=item $language->quant($number, $singular, $plural, $negative)

This is generally meant to be called from inside Bracket Notation
(which is discussed later), as in 

     "Your search matched [quant,_1,document]!"

It's for I<quantifying> a noun (i.e., saying how much of it there is,
while giving the currect form of it).  The behavior of this method is
handy for English and a few other Western European languages, and you
should override it for languages where it's not suitable.  You can feel
free to read the source, but the current implementation is basically