/ 
Lingua-Translate-Google-0.03
River stage zero No dependents
/ Lingua::Translate::Google

NAME

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

SYNOPSIS

use Lingua::Translate;

Lingua::Translate::config
    (
      backend => 'Google',
      api_key => 'YoUrApIkEy',
      referer => 'http://your.domain.tld/yourdir/',
      ua      => LWP::UserAgent->new(),
    );

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

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

DESCRIPTION

Lingua::Translate::Google is a translation back-end for Lingua::Translate that contacts Google (http://ajax.googleapis.com/ajax/services/language/translate/) to do the real work.

It 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.

If you omit the API key config option, then this module uses the fallback service at translate.google.com/ which works fine without it.

To use the Google APIs, Google asks that you obtain an API key, and that you always include a valid and accurate referer URL. If you supply an API key, then this module uses the AJAX API which Google provides specifically for third party application development.

One way or another, by using Google services (either directly or via this module) you are agreeing by their terms of service.

Please read:

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

To obtain your own API key:

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.

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 (http://translate.google.com/translate_a/t?) to calculate available language pairs. The data about available language pairs is cached in memory.

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.

Also, the primary service (at googleapis.com) 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, )

This function sets defaults for use when constructing objects. Options include:

google_uri

The uri to use when contacting Google.

The default value is

"http://ajax.googleapis.com/ajax/services/language/translate?"

 v=1.0
&q=hello%20world
&langpair=en%7Cit
&key=yourapikey

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

Another (yet currently unsported) possibility is:

"http://www.google.com/uds/Gtranslate?"

 v=1.0
&q=hello%20world
&langpair=en%7Czh-TW
&callback=google.language.callbacks.id101
&context=22
&key=notsupplied
&key=yourapikey
google_fallback_uri

The URI used when contacting Google, and no api_key is provided.

The default value is

"http://translate.google.com/translate_a/t?"

 client=t
&text=hello%20world
&sl=en
&tl=zh-Tw

Note, Google states clearly that they want you to obtain and use an API key, and also include a valid and accurate referer URL.

agent

The User-Agent string to use when contacting Google.

The default value is "Lingua::Translate::Google/", plus the version number of the package.

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".

BUGS/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

ACKNOWLEDGEMENTS

This is a rewritten copy of Lingua::Translate::Babelfish by Sam Vilain <enki@snowcra.sh>.

AUTHOR

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