NAME

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

SYNOPSIS

use Lingua::Translate;

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

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

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

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

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

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

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 by their 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

Source language, in RFC-3066 form. See I18N::LangTags for a discussion of RFC-3066 language tags.

As of version 0.06 this option can be omitted or given a value 'auto'.

dest

Destination Language

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/translate_t) 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.

It is assumed that the $text coming in is UTF-8 encoded, and that Google will be returning UTF-8 encoded text. In the case that Google returns some other encoding, then an attempt to convert the result to UTF-8 is made with Unicode::MapUTF8::to_utf8. Observation has indicated that the fallback service (at /translate_a/t) is inclined to return windows-1255 encoded text, despite the value of the 'Accept-Charset' header sent in the request. However, a non-windows user agent string seems to remedy this.

Google returns JSON which assumes the client is JavaScript running with an HTML document. This being the case strings are double encoded. First special characters are converted to HTML entities, and then the ampersands are converted to unicode escape sequences. For example, the string "Harold's" is encoded as "Harold\u0027#39;s". The translate function attempts to return plain old UTF-8 encoded strings without any entities or escape sequences.

agent() : LWP::UserAgent

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

CONFIGURATION FUNCTIONS

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.

google_uri

The uri to use when contacting Google.

The default value is: http://ajax.googleapis.com/ajax/services/language/translate?

For details see: http://code.google.com/apis/ajaxlanguage/documentation/#fonje

agent

The User-Agent string to use when contacting Google.

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

chunk_size

The size to break chunks into before handing them off to Google. The default value is 1000 bytes.

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.

TODO

The chunk_size attribute is a hold-over from the Babelfish algorithm. It is TBD as to what chunk size ought to be set for Google.

There might be a better way to get the available language pairs.

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.

Jerrad Pierce (http://search.cpan.org/~jpierce/) for bug reporting.

AUTHOR

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

cpanm Lingua::Translate::Google

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