NAME

Lingua::Translate - Translate text from one language to another

SYNOPSIS

 use Lingua::Translate;

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

 my $english = "I would like some cigarettes and a box of matches";

 my $german = $xl8r->translate($english); # dies or croaks on error

 # prints "Mein Luftkissenfahrzeug ist voll von den Aalen";
 print $german;

DESCRIPTION

Locale::Translate translates text from one written language to another. Currently this is implemented by contacting Babelfish (http://babelfish.altavista.com/), so see there for the language pairs that are supported. Babelfish uses SysTran (http://www.systran.org/) to perform the translation, and contacting a SysTran translation server directly is also supported (in case your translation needs grow beyond babelfish' capacity).

OVERVIEW

To translate text, you first have to obtain a translation ``handle'' for the language pair (source language, destination language) that you are translating, using a constructor (see CONSTRUCTORS, below). This is returned as a perl object. You can then use this handle to translate arbitrary text, using the ``translate'' method (see METHODS, below).

Depending on the back-end that you are using, either the constructor or the translation will open a connection to a translation server. If there are any network errors or timeouts, then an exception will be thrown. If you want to check for this type of error, you will need to wrap both the constructor and the translation function in an eval { } block.

If you are using a systrans server, you will need to use the ``config'' function to tell this module where your translation server is running, and the port that it is listening on.

Translating is generally a heavily expensive task; you should try to save the results you get back from this module somewhere so that you do not overload Babelfish.

CONSTRUCTORS

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

This function creates a new translation handle and returns it. It takes the following construction options, passed as Option => ``value'' pairs:

src: The source language, in RFC3066 form. See the I18N::LangTags manpage. There is no default.
dest: The destination language in the same form. There is no default.

Additionally, any configuration option that is normally passed to the ``config'' function (see below) may be passed to the ``new'' constructor as well.

METHODS

`translate($text)` : $text

Translates $text and returns the translated text. die on any error.

CONFIGURATION FUNCTIONS

This collection of functions configures general operation of the Lingua::Translate module, which is stored in package scoped variables.

These options only affect the construction of new objects, not the operation of existing objects.

`load_back_end($backend)`

This function loads the specified back-end. Used internally by config(). Returns the package name of the backend.

config(option => $value)

This function sets defaults for use when constructing new objects; it does not affect already constructed objects.

back_end

This specifies the method to use for translation. Currently supported values are ``Babelfish'' and ``SysTran''. The case is significant.

The default value is ``Babelfish''.

Setting this option will ``use'' the appropriate back-end module from Lingua::Translate::*, which should be a derived class of Lingua::Translate.

If the configuration option requested is not found, and a back-end is configured, then that back-end's config function is called with the options.

src_enc

Character set encoding assumed for input text. If the Unicode::MapUTF8 module is not available, this option has no effect and strings are passed on to the translation back end without processing.

The default value is ``utf8''.

dest_enc

Character set encoding assumed for returned text. If the Unicode::MapUTF8 module is not available, this option has no effect and strings are passed back from the translation back end as is.

The default value is ``utf8''.

This function can also be called as an instance method (ie $object->config(name => value), in which case it configures that object only.

BUGS/TODO

No mechanism for backends registering which language pairs they have along with a priority, so that the most efficient back-end for a translation can be selected automatically.

Some much shorter invocation rules, suitable for one liners, etc.

I don't have access to a non-European character set version of SysTran, so translation to/from non-ISO-8859-1 character sets is not currently possible.

Need to formalise and define the ``Interface'' that the back-end modules adhere to.

AUTHOR

Sam Vilain, <enki@snowcra.sh>