NAME
Apache::Language - Perl transparent language support for mod_perl scripts and Apache modules
SYNOPSIS
In YourModule.pm:
sub handler {
my $r = shift;
use Apache::Language;
my %lang;
tie %lang, Apache::Language, $r;
print $lang{'Error01'};
...
}
or without tied-interface
sub handler {
my $r = shift;
use Apache::Language;
my $lang = new Apache::Language ($r);
print $lang->message('Error01');
...
}
Then in YourModule.dic:
en:Error01
This is a bad thing you did!
fr:Error01
Vous venez de faire quelque chose de mauvais!
de:Error01
Fehler!
DESCRIPTION
The goal of this module is to provide a simple way for mod_perl module writers to include support for multiple language requests.
It uses the Accept-Language: field sent by the web-client, to pick the best fit language for it. It's usage is almost transparent and should prove to be quite convenient (and hopefully, efficient).
First, to use it you need to tie an Apache::Language object to a hash that you'll use for the lifetime of your script, whenever you need to print information that might be presented in different languages.
my $r = shift
my %lang;
tie %lang, Apache::Language ,$r;The first time you call that method, a specific language definitions file is parsed and language-key-content pairs are generated. That will be done only once per child httpd process.
After that it's only a matter of using the hash just like an ordinary one, like so:
print $lang{'key'};That will produce the content for the key 'key' in the best fit language for the current request being served. That's it.
Of course you need to set-up the dictionnary file for this to work. If you are writing a module, simply name the file YourModule.dic and place it in the same place your module gets installed.
Apache::Registry Scripts
You can also use Apache::Language with registry scripts with almost the same ease. The only difference is the naming of the Dictionnary file. Since your script might not have an extension to replace with .dic, .dic is simply added after the full name of your script.
Dictionnary files
The format of those Dictionnary files is pretty straight-forward
language:key
content
language:key
content
....Just make sure those empty lines are actually empty. You should make this list balanced, all keys should be translated in the same languages. If not, sometimes Apache::Language might not be able to find a content fitting the request at all. In that case, you will simply get undef back.
The message request was nothing more than a call to printf, and I felt it was not very efficient to call it on every access. It's still there, but if you want to be able to insert small things into your Language-ified tokens, place a few %s in them and call printf yourself :-)
The old ->message('key') interface is still there if you want to call printf on each access.
Anyway, this is the second attempt at building something usefull, easy and efficient (or fast). Feedback very welcome.
TODO
Currently, the language file is only loaded once per child, then cached forever after. Last modification time should be checked so a Dictionnary file modifications would reflect instantly.
SEE ALSO
perl(1), Apache(3).
SUPPORT
Please send any questions or comments to the Apache modperl mailing list <modperl@apache.org> or to me at <gozer@ectoplasm.dyndns.com>
NOTES
This code was made possible by :
Doug MacEachern <dougm@pobox.com> Creator of mod_perl. That should mean enough.
Andreas Koenig <koenig@kulturbox.de> The one I got the idea from in the first place.
The mod_perl mailing-list at <modperl@apache.org> for all your mod_perl related problems.
AUTHOR
Philippe M. Chiasson <gozer@ectoplasm.dyndns.com>
COPYRIGHT
Copyright (c) 1999 Philippe M. Chiasson. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.