NAME

Lingua::Translate::Google - Translation back-end for Google's translation service.

SYNOPSIS

 use Lingua::Translate;

 Lingua::Translate::config
     (
         back_end => 'Google',
         api_key  => 'YoUrApIkEy',
         referer  => 'http://your.domain.tld/yourdir/',
         format   => 'text',
         userip   => '192.168.1.1',
     );

 my $xl8r = Lingua::Translate->new( src => 'de', dest => 'en' );

 # prints 'My hovercraft is full of eels'
 print $xl8r->translate('Mein Luftkissenfahrzeug ist voller Aale') . "\n";

 # switch to auto detect for source language
 $xl8r->config( src => 'auto' );

 # prints 'My hovercraft is full of eels'
 print $xl8r->translate('Mi aerodeslizador está lleno de anguilas') . "\n";

DESCRIPTION

Lingua::Translate::Google is a translation back-end for Lingua::Translate that contacts Google translation service to do the real work. The Google translation API is currently at: http://code.google.com/apis/ajaxlanguage/documentation/#Translation http://code.google.com/apis/ajaxlanguage/documentation/#fonje

Lingua::Translate::Google is normally invoked by Lingua::Translate; there should be no need to call it directly. If you do call it directly, you will lose the ability to easily switch your programs over to alternate back-ends that are later produced.

Please Read

By using Google services (either directly or via this module) you are agreeing to the Google terms of service.

http://www.google.com/accounts/TOS

Referer URL

Google asks that you include a meaningful referer value to identify the API users.

API key

The API key is optional.

http://code.google.com/apis/ajaxfeeds/signup.html

CONSTRUCTOR

new( src => $lang, dest => $lang )

Creates a new translation handle. Determines whether the requested language pair is available and will croak if not.

src

A valid RFC-3066 language tag or 'auto'. See: I18N::LangTags Also see: LIMITATIONS

dest

Destination Language

format

Either 'html' or 'text'. This indicates the type of content your sending Google's way. If you omit, then a guess is made based on the submitted text.

userip

This is the IP address of your end user which Google encourages you to supply.

Other options that may be passed to the config() function (see below) may also be passed as arguments to this constructor.

METHODS

The following methods may be called on Lingua::Translate::Google objects.

available() : @list

Returns a list of available language pairs, in the form of 'XX_YY', where XX is the source language and YY is the destination. If you want the english name of a language tag, call I18N::LangTags::List::name() on it. See I18N::LangTags::List.

This method contacts Google (at http://translate.google.com/#) and parses from the HTML the available language pairs. The list of language pairs is cached for subsequent calls.

You may also use this method to see if a given language tag is available.

 die "doesn't have 'he'"
     if !$xl8tr->available('he');

translate($text) : $translated

Translates the given text, or die's on any kind of error.

Incomming $text should be UTF-8 encoded.

If you may also call translate in list context to get a hash of information about the translation query. In order for this to work you must bypass the Lingua::Translate interface and create an instance of Lingua::Translate::Google directly.

 my $xl8r = Lingua::Translate::Google->new( src => 'auto', dest => 'en' );

 my %xl8td = $xl8r->translate('Mein Luftkissenfahrzeug ist voller Aale');

 print 'xl8td: ', Data::Dumper::Dumper( \%xl8td );

    xl8td: $VAR1 = {
        'dest'   => 'en',
        'q'      => 'Mein Luftkissenfahrzeug ist voller Aale',
        'src'    => 'de',
        'result' => 'My hovercraft is full of eels'
    };

This feature is useful if you're specifying 'auto' and you want to see what Google identifies as the source language.

agent() : LWP::UserAgent

Returns the LWP::UserAgent object used to contact Google.

CONFIG OPTIONS

config( option => $value, )

Use this to set any of these options:

api_key

The API key is not required. But you're invited to use one as a secondary means of identifying yourself.

See: http://code.google.com/apis/ajaxfeeds/signup.html

referer

The value for the referer header in HTTP requests sent to the Google translation service.

Google requests that you provide a valid referer string as the primary means of identifying yourself. You will probably use the URL you specified when you got your API key, or perhaps the URL where your application exists.

agent

The User-Agent string to use when contacting Google.

The default value is: Lingua::Translate::Google/0.10

retries

The number of times to retry contacting Google if the first attempt fails. The default value is 2.

src

The source language. Same as constructor src option.

dest

The destination language. Same as constructor dest option.

save_auto_lookup

Default value is true. When using the 'auto' src option, this causes the result of the first language detect query to be saved and used on subsequent calls to translate. Set this option to false to require that each call to translate redetect the source language.

If you're doing a lot of queries and the source language is expected to be the same for all of them then this option should reduce the number of HTTP requests by 1/2 - 1.

LIMITATIONS

This module supports 'auto' src tag for auto detecting the source language. However, the calling module Lingua::Translate enforces that language tags are valid according to I18N::LangTags::is_language_tag. To prevent this from being a problem, you need to allow Lingua::Translate::Google to be evaluated before the constructor call.

For example:

 use Lingua::Translate;

 Lingua::Translate::config(
     back_end => 'Google',
 );

 my $xl8r = Lingua::Translate->new(
     src      => 'auto',
     dest     => 'de',
 );

Or:

 use Lingua::Translate::Google;

 my $xl8r = Lingua::Translate->new(
     back_end => 'Google',
     src      => 'auto',
     dest     => 'de',
 );

This will fail:

 use Lingua::Translate;

 my $dies = Lingua::Translate->new(
     back_end => 'Google',
     src      => 'auto',
     dest     => 'de',
 );

SEE ALSO

Lingua::Translate, Lingua::Translate::Babelfish, LWP::UserAgent, Unicode::MapUTF8

LICENSE

This is free software, and can be used/modified under the same terms as Perl itself.

ACKNOWLEDGEMENTS

Sam Vilain (http://search.cpan.org/~samv/) wrote Lingua::Translate::Babelfish which served as the basis for this module.

Andrew Nugged (http://ladoshki.com/) provided some crucial bug fixes and drove me to release 0.11.

AUTHOR

Dylan Doxey, <dylan.doxey@gmail.com>

cpanm Lingua::Translate::Google

perl -MCPAN -e shell
install Lingua::Translate::Google