/ 
Locale-Maketext-Gettext-1.01
River stage one • 1 direct dependent • 9 total dependents
/ Locale::Maketext::Gettext::Functions

NAME

Locale::Maketext::Gettext::Functions - Functional interface to Locale::Maketext::Gettext

SYNOPSIS

use Locale::Maketext::Gettext::Functions;
bindtextdomain(DOMAIN, LOCALEDIR);
textdomain(DOMAIN);
get_handle();
print __("Hello, world!\n");

DESCRIPTION

This is the functional interface to Locale::Maketext::Gettext (and Locale::Maketext).

The maketext function attempts to translate a text string into the user's native language, by looking up the translation in a message catalog.

FUNCTIONS

bindtextdomain(DOMAIN, LOCALEDIR);

Register a text domain with a locale directory. Return LOCALEDIR itself. If LOCALEDIR is omitted, the registered locale directory of DOMAIN is returned. This method always success.

textdomain(DOMAIN);

Set the current text domain. Return the DOMAIN itself. if DOMAIN is omitted, the current text domain is returned. This method always success.

$message = maketext($key, @param...);

Attempts to translate a text string into the user's native language, by looking up the translation in a message catalog. Refer to Locale::Maketext(3) for the details on its c<maketext> method.

$message = __($key, @param...);

A synonym to maketext(). This is a shortcut to maketext() so that it is cleaner when you employ maketext to your existing project.

($key, @param...) = N_($key, @param...);

Return the original text untouched. This is to enable the text be catched with xgettext.

reload_text();

Purge the MO text cache. By default MO files are cached after they are read and parse from the disk, to reduce I/O and parsing overhead on busy sites. reload_text() purges this cache. The next time maketext is called, the MO file will be read and parse from the disk again. 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.

%Lexicon = read_mo($MOfile);

Read and parse the MO file. Return the read %Lexicon. The returned lexicon is in its original encoding.

If you need the meta infomation of your MO file, parse the entry $Lexicon{""}. For example:

/^Content-Type: text\/plain; charset=(.*)$/im;
$encoding = $1;

NOTES

WARNING: Due to the design of perl itself, run-time removal of a locale from your package does not work. Locale::Maketext(3) finds a language handle by looking for a valid subclass package, and run-time unloading of a package is not available to perl. You always have to restart your application if you remove an MO file. This includes restarting a mod_perl-enabled Apache.

For the same reason, rebinding of a text domain to another locale directory may not work as you expected. Declared subclass packages cannot be taken back. Solutions may be possible, though.

STORY

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 have always have to do this in my every application, why shouldn't I 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) doesn't 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

BUGS

encoding not supported yet

Source text encoding and output encoding is not supported yet. Locale::Maketext::Gettext::Functions is still not multibyte-safe. Solutions or suggestions are welcome.

lookup failure control not supported yet

Solutions or suggestions are welcome.

SEE ALSO

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/manual/gettext/.

AUTHOR

imacat <imacat@mail.imacat.idv.tw>

COPYRIGHT

Copyright (c) 2003 imacat. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.