/ 
WebService-Google-Language-0.14
River stage zero No dependents
/ WebService::Google::Language

NAME

WebService::Google::Language - Perl interface to the Google AJAX Language API

DEPRECATION WARNING

Please take note of this statement by Google (see links): "With the exception of the Translate v2 API, which is now available as a paid service, the APIs included in this family have all been deprecated."

The v1 API, which this module is based on, WILL BE SHUT OFF COMPLETELY on Dec 1, 2011 (see http://code.google.com/apis/language/translate/overview.html).

The live tests of this module already started failing sporadically on Oct 29 and are now disabled by default. To check if the API is still working try:

export WGL_FORCE_LIVE_TESTS=1 && perl -Ilib -T t/05-methods.t

SYNOPSIS

use WebService::Google::Language;

my $service = WebService::Google::Language->new(
  referer => 'http://example.com/',
  src     => '',
  dest    => 'en',
);

my $result = $service->translate('Hallo Welt');
if ($result->error) {
  printf "Error code: %s\n", $result->code;
  printf "Message:    %s\n", $result->message;
}
else {
  printf "Detected language: %s\n", $result->language;
  printf "Translation:       %s\n", $result->translation;
}

$result = $service->detect('Bonjour tout le monde');
printf "Detected language: %s\n", $result->language;
printf "Is reliable:       %s\n", $result->is_reliable ? 'yes' : 'no';
printf "Confidence:        %s\n", $result->confidence;

DESCRIPTION

WebService::Google::Language is an object-oriented interface to the Google AJAX Language API (http://code.google.com/apis/ajaxlanguage/).

The AJAX Language API is a web service to translate and detect the language of blocks of text.

CONSTRUCTOR

$service = WebService::Google::Language->new(%options);

Creates a new WebService::Google::Language object and returns it.

Key/value pair arguments set up the initial state:

Key       Usage         Expected value
---------------------------------------------------------
referer   mandatory     HTTP referer
src       optional      default source language
dest      optional      default destination language
key       recommended   application's key
ua        optional      an LWP::UserAgent object for reuse
json      optional      a JSON object for reuse

Since Google demands a "valid and accurate http referer header" in requests to their service, a non-empty referer string must be passed to the constructor. Otherwise the constructor will fail.

Unless the key 'ua' contains an instance of LWP::UserAgent, any additional entries in the %options hash will be passed unmodified to the constructor of LWP::UserAgent, which is used for performing the requests.

E.g. you can set your own user agent identification and specify a timeout this way:

$service = WebService::Google::Language->new(
  referer => 'http://example.com/',
  agent   => 'My Application 2.0',
  timeout => 5,
);

Or reuse existing instances of LWP::UserAgent and JSON respectively:

$service = WebService::Google::Language->new(
  referer => 'http://example.com/',
  ua      => $my_ua_obj,
  json    => $my_json_obj,
);
$service = WebService::Google::Language->new($referer);
$service = WebService::Google::Language->new($referer, %options);

Since the referer is the only mandatory parameter, the constructor can alternatively be called with an uneven parameter list. The first element will then be taken as the referer, e.g.:

$service = WebService::Google::Language->new('my-valid-referer');

METHODS

$result = $service->translate($text, %args);
$result = $service->translate(%args);

The translate method will request the translation of a given text.

Either place the $text as the first parameter to this method or store it into the arguments hash using the key 'text'.

The source and the destination language can be specified as values of the keys 'src' and 'dest'. If these parameters are missing, the default values specified on construction of the object will be used.

If the object has been constructed without default values, the translate request will default to an empty string for the source language - i.e. Google will attempt to identify the language of the given text automatically. The destination language will be set to English (en).

Examples:

# initialize without custom language defaults
$service = WebService::Google::Language->new('http://example.com/');

# auto-detect source language and translate to English
# (internal defaults)
$result = $service->translate('Hallo Welt');

# auto-detect source language and translate to French (fr)
$result = $service->translate( 'Hallo Welt', dest => 'fr' );

# set source to English and destination to German (de)
%args = (
  text => 'Hello world',
  src  => 'en',
  dest => 'de',
);
$result = $service->translate(%args);

See Google's documentation for supported languages, language codes and valid language translation pairs.

$result = $service->detect($text);
$result = $service->detect( text => $text );

The detect method will request the detection of the language of a given text. $text is the single parameter and can be passed directly or as key 'text' of a hash.

$result = $service->detect_language($text);

If detect as a method name is just not descriptive enough, there is an alias detect_language available.

Examples:

# detect language
$result = $service->detect('Hallo Welt');
# using the more verbose alias
$result = $service->detect_language('Hallo Welt');
$boolean = $service->ping;

Checks if internet access to Google's service is available.

$json = $service->json;

Returns the JSON object used by this instance.

$service = $service->json($json);

Sets the JSON object to be used by this instance. Setters return their instance and can be chained.

$ua = $service->ua;
$service = $service->ua($ua);

Returns/sets the LWP::UserAgent object.

$referer = $service->referer;
$service = $service->referer($referer);

Returns/sets the referer string.

RESULT ACCESSOR METHODS

Google returns the result encoded as a JSON object which will be automatically turned into a Perl hash with identically named keys. See the description of the JSON response at Google's page for the meaning of the JavaScript properties, which is identical to the Perl hash keys.

To provide some convenience accessor methods to the result, the hash will be blessed into the package WebService::Google::Language::Result. The method names are derived from Google's JavaScript class reference of the AJAX Language API.

The accessors marked as 'no' in the following table will always return undef for a result from translate or detect respectively.

Accessor   translate  detect  description
---------------------------------------------------------------------
error         yes      yes    a hash with code and message on error
code          yes      yes    HTTP-style status code
message       yes      yes    human readable error message
translation   yes      no     translated text
language      yes      yes    detected source language
is_reliable   no       yes    reliability of detected language
confidence    no       yes    confidence level, ranging from 0 to 1.0

The "SYNOPSIS" of this module includes a complete example of using the accessor methods.

LIMITATIONS

Google does not allow submission of text exceeding 5000 characters in length to their service (see Terms of Use). This module will check the length of text passed to its methods and will fail if text is too long (without sending a request to Google).

TODO

SEE ALSO

AUTHOR

Henning Manske <hma@cpan.org>

ACKNOWLEDGEMENTS

Thanks to Igor Sutton (IZUT) for submitting a patch to enable the use of proxy environment variables within LWP::UserAgent.

Thanks to Ilya Rubtsov for pointing out Google's change of the text length limitation (see Terms of Use) and the existing server-side length limitation of URLs when using GET request method.

COPYRIGHT AND LICENSE

Copyright (c) 2008-2011 Henning Manske. All rights reserved.

This module is free software. You can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/.

This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.