Locale::Maketext::Gettext::Functions - Functional interface to Locale::Maketext::Gettext |
Locale::Maketext::Gettext::Functions - Functional interface to Locale::Maketext::Gettext
use Locale::Maketext::Gettext::Functions; bindtextdomain(DOMAIN, LOCALEDIR); textdomain(DOMAIN); get_handle("de"); print __("Hello, world!\n");
Locale::Maketext::Gettext::Functions is a functional interface to Locale::Maketext::Gettext(3) (and Locale::Maketext(3)). It works exactly the GNU gettext way. It plays magic to Locale::Maketext(3) for you. No more localization class/subclasses and language handles are required at all.
The maketext
, dmaketext
, pmaketext
and dpmaketext
functions attempt to translate a text message into the native
language of the user, by looking up the translation in an MO lexicon
file.
LOCALEDIR
itself. If LOCALEDIR
is omitted, the registered locale directory
of DOMAIN
is returned. This method always success.
textdomain(DOMAIN)
DOMAIN
itself. if
DOMAIN
is omitted, the current text domain is returned. This
method always success.
get_handle(@languages)
get_handle
.
maketext
plural
grammer.
maketext()
. This is a shortcut to maketext()
so
that it is cleaner when you employ maketext to your existing project.
encoding(ENCODING)
undef
, to return
the result in unencoded UTF-8.
key_encoding(ENCODING)
maketext
method itself is not multibyte-safe to the _AUTO lexicon. If you are
using your native non-English language as your original text and you
are having troubles like:
Unterminated bracket group, in:
Then, specify the key_encoding
to the encoding of your original
text. Returns the current setting.
WARNING: You should always use US-ASCII text keys. Using non-US-ASCII keys is always discouraged and is not guaranteed to be working.
encode_failure(CHECK)
CHECK
. The default is FB_DEFAULT
,
which is a safe choice that never fails. But part of your text may
be lost, since that is what FB_DEFAULT
does. Returns the current
setting.
die_for_lookup_failures(SHOULD_I_DIE)
reload_text()
reload_text()
purges this cache, so that updated MO
files can take effect at run-time. This is used when your MO file is
updated, but you cannot shutdown and restart the application. for
example, when you are a co-hoster on a mod_perl-enabled Apache, or
when your mod_perl-enabled Apache is too vital to be restarted for
every update of your MO file, or if you are running a vital daemon,
such as an X display server.
read_mo($MOfile)
If you need the meta infomation of your MO file, parse the entry
$Lexicon{""}
. For example:
/^Content-Type: text\/plain; charset=(.*)$/im; $encoding = $1;
NOTE: Since localization classes are generated at run-time, it is
not possible to override the Maketext language functions, like
quant
or numerate
. If that is your concern, use
Locale::Maketext::Gettext(3) instead.
Suggestions are welcome.
You can now add/remove languages/MO files at run-time. This is a major improvement over the original Locale::Maketext::Gettext(3) (and Locale::Maketext(3)). This is done by registering localization classes with random IDs, so that the same text domain can be re-declared infinitely, whenever needed (language list changes, LOCALEDIR changes, etc.) This is not possible to the object-interface of Locale::Maketext::Gettext(3) (and Locale::Maketext(3)).
Language addition/removal takes effect only after bindtextdomain
or textdomain
is called. It has no effect on maketext
calls.
This keeps a basic sanity in the lifetime of a running script.
If you set textdomain
to a domain that is not bindtextdomain
to
specific a locale directory yet, it will try search system locale
directories. The current system locale directory search order is:
/usr/share/locale, /usr/lib/locale, /usr/local/share/locale,
/usr/local/lib/locale. Suggestions are welcome.
The idea is that: I finally realized that, no matter how hard I try,
I can never get a never-failure maketext
. A common wrapper
like:
sub __ { return $LH->maketext(@_) };
always fails if $LH is not initialized yet. For this reason,
maketext
can hardly be employed in error handlers to output
graceful error messages in the natural language of the user. So,
I have to write something like this:
sub __ { $LH = MyPkg::L10N->get_handle if !defined $LH; return $LH->maketext(@_); }
But what if get_handle
itself fails? So, this becomes:
sub __ { $LH = MyPkg::L10N->get_handle if !defined $LH; $LH = _AUTO->get_handle if !defined $LH; return $LH->maketext(@_); } package _AUTO; use base qw(Locale::Maketext); package _AUTO::i_default; use base qw(Locale::Maketext); %Lexicon = ( "_AUTO" => 1 );
Ya, this works. But, if I always have to do this in my every application, why should I not make a solution to the localization framework itself? This is a common problem to every localization projects. It should be solved at the localization framework level, but not at the application level.
Another reason is that: Programmers should be able to use
maketext
without the knowledge of object-oriented programming.
A localization framework should be neat and simple. It should lower
down its barrier, be friendly to the beginners, in order to
encourage the use of localization and globalization. Apparently
the current practice of Locale::Maketext(3)
does not satisfy this request.
The third reason is: Since
Locale::Maketext::Gettext(3) imports
the lexicon from foreign sources, the class source file is left
empty. It exists only to help the get_handle
method looking for
a proper language handle. Then, why not make it disappear, and be
generated whenever needed? Why bother the programmers to put
an empty class source file there?
How neat can we be?
imacat, 2003-04-29
Since maketext localization classes are generated at run time,
Maketext language function override, like quant
or numerate
, is
not available here. Suggestions are welcome.
encoding
, key_encoding
, encode_failure
and
die_for_lookup_failures
are not mod_perl-safe. These settings
affect the whole process, including the following scripts it is
going to run. This is the same as setlocale
in
POSIX(3). Always set them at the very beginning of your
script if you are running under mod_perl. If you do not like it,
use the object-oriented
Locale::Maketext::Gettext(3) instead.
Suggestions are welcome.
Smart translation between Traditional Chinese/Simplified Chinese, like what GNU gettext does, is not available yet. Suggestions are welcome.
Locale::Maketext(3), Locale::Maketext::TPJ13(3), Locale::Maketext::Gettext(3), bindtextdomain(3), textdomain(3). Also, please refer to the official GNU gettext manual at http://www.gnu.org/software/gettext/manual/.
imacat <imacat@mail.imacat.idv.tw>
Copyright (c) 2003-2008 imacat. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Locale::Maketext::Gettext::Functions - Functional interface to Locale::Maketext::Gettext |