WebService::Google::LaUsergContributed Perl DocWebService::Google::Language(3)NAMEWebService::Google::Language - Perl interface to the Google AJAX
Language API
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;
DESCRIPTIONWebService::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
· Batch Interface
Incorporate the Batch Interface into this module
(<http://code.google.com/apis/ajaxlanguage/documentation/reference.html#_batch_interface>).
· Documentation
Explain the server-side length limitation of URLs for GET requests
which (currently) must be used by the "detect" method.
SEE ALSO
· Google AJAX Language API
<http://code.google.com/apis/ajaxlanguage/>
· Terms of Use
<http://code.google.com/apis/ajaxlanguage/terms.html>
· Supported languages
<http://code.google.com/apis/ajaxlanguage/documentation/#SupportedLanguages>
· Class reference
<http://code.google.com/apis/ajaxlanguage/documentation/reference.html>
· LWP::UserAgent
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-2010 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.
perl v5.14.1 2010-12-31 WebService::Google::Language(3)
