NAME

AltaVista::BabelFish - Perl OO interface to http://babelfish.altavista.com

SYNOPSIS

    use AltaVista::BabelFish;
    
    my $phish = AltaVista::BabelFish->new();
or
    my $phish = AltaVista::BabelFish->new({ source => $src });
or
    my $phish = AltaVista::BabelFish->new({ target => $trg });
or
    my $phish = AltaVista::BabelFish->new({ source => $src, target => $trg });
  

If $source and/or $target are not specified it defaults to 'en' and 'es' respectively.

DESCRIPTION

This module gives an object oriented interface to http://babelfish.altavista.com to add translation ability to your script.

Object methods

$phish->translate()

This communicates with babelfish.altavista.com to do the actual translating.

You can optionally give new source and target languages for this translation. Setting these does not change the languages for the object it changes them only for this call.

    my $trans = $phish->translate($str,$source,$target);
    my $trans = $phish->translate($str,$source);
    my $trans = $phish->translate($str,0,$target); # 0 or '' or undef (IE false)
    my $trans = $phish->translate($str) or die $phish->get_errstr();;
    my($trans, $kls, $ienc) = $phish->translate($str) or die $phish->get_errstr();
    

$kls and $ienc are the values of the hidden fields of the same name in the "Search the web with this text" form of the results page.

If you have multiple strings you want translated into the same source and target languages specify them in an array ref as the first argument:

    my $result_array_ref = $phish->translate($string_array_ref) or die $phish->errstr();
    

The resulting array ref has the translated versions in the same positions:

    my $result_array_ref = $phish->translate(["hello", "goodbye", "thank you", "you are welcome"],'en','fr') or die $phish->errstr();
    print join ', ', @{ $result_array_ref }; # prints : bonjour, au revoir, merci, vous ?tes bienvenu
    

And you only have to make one HTTP call to the internet instead of one per item to translate.

With an array ref $kls and $ienc are still available in array context.

    my ($result_array_ref, $ls, $ienc) = $phish->translate(["hello", "goodbye", "thank you", "you are welcome"],'en','fr') or die $phish->errstr();
   

In all cases if $source and/or $target are not specified it uses what was previously set.

$phish->get_errstr()

Returns any errors encountered translate()ing as a string.

$phish->get_source()

Returns the current source language.

     my $src = $phish->get_source(); 
    

$phish->set_source()

Sets the source language

    $phish->set_source('fr');
    

sets the source langauge to 'fr'

If an invalid argument is specified then it is not changed and the original (IE still current) langauge is used.

If the current target is not supported by the new source language the target is changed to the first target language for the source language.

$phish->get_target()

Returns the current source language.

    my $trg = $phish->get_target(); 
    

$phish->set_target($lang)

Sets the target langauge.

    $phish->set_target('fr');
    

sets the target langauge to 'fr'

If an invalid argument is specified then it is not changed and the original (IE still current) langauge is returned.

$phish->get_english()

It returns a string that is the English version of the given language or if nothing is given (or an invalid langauage) then it returns the current source language's name.

    my $source_name = $phish->get_english();
    

$source_name is now "English" (or whatever you had changed the source language to of course)

    my $zt_name = $phish->get_english('zt');
    

$zt_name is now "Chinese Traditional"

$phish->get_native()

Like get_english() but returns the given language's name in the given language.

    my $german = $phish->get_native('de');
    # $german is 'Deutsch'
    

This gets funky for some languages/character sets. See Locales::Language for more info.

$phish->get_target_languages_arrayref()

Returns an array reference of the target languages for the given language or the current source language if nothing is specified.

    my $lang = 'it';
    print $phish->get_english($lang) . " can be translated into the following languages:\n";
    for(@{ $phish->get_target_languages_arrayref($lang) }) {
        print $phish->get_english($_), "\n"; 
    } 
   
    print $phish->get_english() . " can be translated into the following languages:\n";
    for(@{ $phish->get_target_languages_arrayref() }) {
        print $phish->get_english($_), "\n";
    }
    

$phish->get_source_languages_arrayref()

Returns an array reference of all the languages that can be translated into the given langauge. If no [valid] language is given, an array ref of all available source languages is returned

    my $can_be_translated_into_dutch_array_ref = $phish->get_source_languages_arrayref('nl');
    my $all_source_languages_array_ref         = $phish->get_source_languages_arrayref(); 
    
    for my $src (@{ $phish->source_languages_arrayref }) {
        print $phish->get_english($src) . " can be translated into from the following languages:\n";
        for($phish->get_source_languages_arrayref($src) }) {
            print $phish->english($_),"\n";
        }
    }
    

$phish->is_latest_version()

Since its always possible that AltaVista could change around their site this module could need reconfigured on occasion.

This function will check to see if your version is the latest.

     die $phish->get_errstr() if !$phish->is_latest_version();
or perhaps:
     update_modules_according_to_our_policy(ref $phish) if !$phish->is_latest_version();
 

If you have IO::Redirect installed, the verbose output from the CPAN module is stored in $phish->get_errstr() if there is a problem. Otherwise the CPAN functions will have output that you can't control, so its recommended you install IO::Redirect if its not already.

$phish->get_languages_hashref()

Returns a hashref of language info. It can be used to view all the available languages, their name, targets, and two letter code. It is probably most usefull if you need to reference what the two letter code is for a given langauge.

    use Data::Dumper;
    print Dumper $phish->get_languages_hashref; # AltaVista::BabelFish->get_languages_hashref works also
    

$phish->fishinfo()

Returns content for an html page (no header) if called via a browser (IE !-t STDIN) and a text page if via CLI (IE -t STDIN) In void context prints its info, otherwise it returns it.

    print CGI::header();
    print $htmltop;
    print $phish->fishinfo(); # AltaVista::BabelFish->fishinfo() works also
    print $htmlbot;
    

If given a true argument the language's $phish->get_native() is printed out along with it if its not the same as the english version.

$phish->get_native() results gets funky for some languages/character sets. See Locales::Language for more info.

DON'T PANIC

Just a personal note about what this module means to me. I like it because it combines two of my favorite things: Perl and the world of Douglas Adams

So I'd like to say "print $thanks for 1..1000000;" to Mr. Wall for Perl and to Mr. Adams: So long and thanks for all the fish, we'll miss you buddy :)

SEE ALSO

LWP::UserAgent, CPAN, IO::Redirect, Locales::Language

AUTHOR

Daniel Muey, http://drmuey.com/cpan_contact.pl

COPYRIGHT AND LICENSE

Copyright 2005 by Daniel Muey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.