NAME

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

SYNOPSIS

# 
# Translate a string.
# 
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');


# 
# Perhaps you'd like to build a collection of translations.
# 
use Lingua::Translate;
use Data::Dumper;

my $src = 'en';

my %source_lang = (
    hovercraft_eels    => 'My hovercraft is full of eels.',
    cigarettes_matches => 'I would like some cigarettes and a box of matches.',
    hello_world        => 'Hello world.'
);

my %result_lang;

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

DEST:
for my $dest (qw( iw pt ro fr de hi es ja zh-CN )) {

    my $xl8r = Lingua::Translate->new(
        src      => $src,
        dest     => $dest,
    ) or die "No translation server available for $src -> $dest";

    TOKEN:
    for my $token ( keys %source_lang ) {

        my $source_text = $source_lang{$token};

        $result_lang{$dest}->{$token} = $xl8r->translate($source_text);
    }
}

print Dumper( \%result_lang ) . "\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://ajax.googleapis.com/ajax/services/language/translate/.

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.

If you omit the API key config option, then this module uses the fallback service at translate.google.com/ which works fine without it, on the condition that the referer is the URL of the translate service.

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

To obtain your API key:

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.

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 (at the configured google_fallback_uri) and parses from the HTML the available language pairs. The list of language pairs is cached for subsequent calls.

As of Lingua::Translate version 0.09, calls to this method don't propogate from the Lingua:Translate namespace. Rather, this method is only available in the Lingua::Translate::Google namespace.

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.

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:

api_key

This key is issued to you by Google and it gives you access to the AJAX API which is the translation service intended for application development.

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. You will probably use the one you specified when you got your API key. If you're not specifying an API key, then the fall-back translator will reject (with a "403 Forbidden" response) any request which does not have the translator URL as its referer.

The translate function will make sure you have a referer value that works, and will warn if it's overwriting the value you specified.

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. This is the AJAX service used by the public translate site.

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.

google_translate_uri

This is the URL of the Google page where the available languages are parsed from. The "item available()_:_@list" method uses this URI to get some HTML which is presumed to have a select list for the source and destination languages.

The default value is

"http://translate.google.com/translate_t#"

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

DIAGNOSTICS

Expect to see a warning if you're using the api_key and omitting the referer. Also, expect to see a warning if you're omitting the api_key and specifying a custom referer. This is because the Google translation service cares about your referer values. This module will warn whenever it's changing what you specified to make the translation work.

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.

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@cpan.org>

To install Lingua::Translate::Google, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Lingua::Translate::Google

CPAN shell

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

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

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

METHODS

available() : @list

translate($text) : $translated

agent() : LWP::UserAgent

CONFIGURATION FUNCTIONS

config( option => $value, )

DIAGNOSTICS

TODO

SEE ALSO

LICENSE

ACKNOWLEDGEMENTS

AUTHOR

Module Install Instructions