/ 
WWW-WorldLingo-0.03
River stage zero No dependents
/ WWW::WorldLingo

NAME

WWW::WorldLingo - Tie into WorldLingo's subscription based translation service.

VERSION

0.03

SYNOPSIS

use WWW::WorldLingo;
my $wl = WWW::WorldLingo->new();
$wl->srclang("en");
$wl->trglang("it");
my $italian = $wl->translate("Hello world")
   or die $wl->error;
print $italian, "\n";

DESCRIPTION

This module makes using WorldLingo's translation API simple. The service is subscription based. They do not do free translations except as randomly chosen test translations; e.g., you might get back Spanish, German, Italian, etc but you won't know which till it's returned. Maximum of 25 words for tests.

If you are not a subscriber, this module is mostly useless.

INTERFACE

See the WorldLingo API docs for clarification and more information: http://www.worldlingo.com/

$wl = WWW::WorldLingo->new(\%opt)

Create a WWW::WorldLingo object. Can accept any of its attributes as arguments. Defaults to the test account WorldLingo provides.

$wl->data($what_to_translate)

Set/get the string (src) to be translated. You can use the translate method to feed the object its src data too.

$wl->request

If you want to bypass WWW::WorldLingo manually making an HTTP request and take the HTTP::Request object and do something with it yourself.

$wl->parse

Likewise if you want have bypassed a translate call or stored a response, you can reconstitute--to a degree--the WWW::WorldLingo object by using parse on the HTTP::Response.

Returns a WWW::WorldLingo object which attempts to represent one which would create an identical response if sent back to the WorldLingo server.

$wl->translate([$data])

Perform the translation of the data and return the result (trg). Accepts new data so the object can be reused easily.

If nothing is returned, there was an error. Errors can either be set by the API -- you did something wrong in your call or they have a problem -- or the requesting agent -- you have some sort of connection issues.

$wl->result

What translate returns.

$wl->error

A text string of the error.

$wl->error_code

The code of the error. If it's from WorldLingo, it's a proprietary number. If it's from the user agent, it's the HTTP status code.

$wl->api

The URI for service calls.

$wl->scheme

"http" [default] or "https."

$wl->agent

The web agent. You can set your own or WWW::WorldLingo Tries to use LWPx::ParanoidAgent and falls back to LWP::UserAgent if it must. You can provide your own as long as it's a subclass of LWP::UserAgent (like WWW::Mechanize) or a class which offers the same hooks into the HTTP::Requests and HTTP::Responses.

You can override or change agents at any time.

$wl->mimetype
$wl->encoding
$wl->subscription

Your WorldLingo subscription ID. The default is their test account, S000.1.

$wl->password

Your WorldLingo password. The default is for their test account, secret.

$wl->srclang

The language your original data is in.

$wl->trglang

The language you want returned as translated.

$wl->srcenc

The encoding of your original language.

$wl->trgenc

The encoding you want back for your translated text.

$wl->dictno

WorldLingo allows paid users to build their own dictionaries to deal with custom terminology and filtering.

$wl->gloss

WorldLingo has special glossaries to try to improve translation quality.

$wl->api_mode

Should come back "TEST MODE ONLY - Random Target Languages" for tests.

DIAGNOSTICS

See HTTP::Status for error codes thrown by the agent. Here is a short list of WorldLingo diagnostics.

Error code   Error
     0       Successful
    26       Incorrect password
    28       Source language not in subscription
    29       Target language not in subscription
   176       Invalid language pair
   177       No input data
   502       Invalid Mime-type
  1176       Translation timed out

Access this information after a failed translation request with error_code and error.

DEPENDENCIES

HTTP::Request::Common, LWP::UserAgent, Carp, an Internet connection.

TO DO

Better tests. Very little of the real object is being looked at by the tests right now.

Get the API from WorldLingo that comes with a subscription account to fill in the blanks.

Support for multiple requests at once, partitioned in XHTML so they can be separated back out on return.

Docs for the Mime stuff.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-www-worldlingo@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Ashley Pond V, <ashley@cpan.org>.

LICENCE AND COPYRIGHT

Copyright (c) 2007, Ashley Pond V.

This module is free software; you can redistribute it and modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

Because this software is licensed free of charge, there is no warranty for the software, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the software "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair, or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.