/ 
MetaTrans-1.05
River stage zero No dependents
/ MetaTrans

NAME

MetaTrans - Class for creating multilingual meta-translators

SYNOPSIS

use MetaTrans;

my $mt = new MetaTrans;

# plug-ins we want to use
my @plugin_classes = (
    'MetaTrans::UltralinguaNet',
    'MetaTrans::SlovnikCz',
    'MetaTrans::SeznamCz',
);

foreach my $plugin_class (@plugin_classes)
{
    # load module
    eval "require $plugin_class";

    # instantiate
    my $plugin = new $plugin_class;

    # plug the plug-in in :)
    $mt->add_translators($plugin);
}

# plug-ins which support English to Czech translation
@translators = $mt->get_translators_for_direction('eng', 'cze');

# if we have at least one we will perform a translation of 'dog'
if (@translators > 0)
{
    $mt->run_translators('dog', 'eng', 'cze');
    my @translations;
    while (my $translation = $mt->get_translation)
        { push @translations, $translation; }

    # we want the output to be sorted
    my @sorted_translations = MetaTrans::sort_translations(@translations);
    print join("\n", @sorted_translations) . "\n";
}

You are also encouraged to trying the Perl/Tk frontend. Simply run

metatrans

DESCRIPTION

The MetaTrans class provides an interface for making multilingual translations using multiple data sources (translators). Its design is especially suitable for extracting data from online translators like http://www.ultralingua.net/.

To do something useful a MetaTrans object must be provided with plug-ins for extracting data from every source to be used. By now creating a plug-in from a scratch might be a bit complicated for some ugly hacks had to be made in the originally clean design of MetaTrans to make it working in Perl/Tk applications. Hopefully this is going to change in some of the future releases.

Currently the only recommended way for creating MetaTrans plug-ins is by derriving from the MetaTrans::Base class. See MetaTrans::Base for information on how to do so.

CONSTRUCTOR METHODS

MetaTrans->new(@translators)

This method constructs a new MetaTrans object and returns it. Translators array argument may be provided to plug in desired translators.

METHODS

$mt->add_translators(@translators)

Plug in one or more translators.

$mt->get_translators

Return an array of all plug-ins being used.

$mt->enable_translator($trans)

Enable the translator. The argument is an object.

$mt->disable_translator($trans)

Disable the translator. The argument is an object.

$mt->toggle_enabled_translator($trans)

Togle translator's enabled/disabled status. The argument is an object.

$mt->is_enabled_translator($trans)

Returns true value if the translator is enabled, false otherwise. The argument is an object.

$mt->get_translators_state($trans)

Returns current state of the translator. Possible values are

VALUE       MEANING
---------   --------------------------------------------------------
"ok"        successfully finished a translation (initial state, too)
"busy"      working on a translation
"timeout"   a timeout occured when querying an online translator
"error"     unknown error occured when queryign an online translator
$mt->get_all_src_lang_codes

Returns a list of language codes, which some of the enabled plug-ins are able to translate from.

The method calls the get_all_src_lang_codes method for all enabled plug-ins (see MetaTrans::Base) and unions results.

$mt->get_dest_lang_codes_for_src_lang_code($src_lang_code)

Returns a list of language codes, which some of the enabled plug-ins are able to translate to from the language with $src_lang_code.

The method calls the get_dest_lang_codes_for_src_lang_codes method for all enabled plug-ins (see MetaTrans::Base) and unions results.

$mt->get_translators_for_direction($src_lang_code, $dest_lang_code)

Retuns an array of enabled tranlators, which support the translation direction from language with $src_lang_code to language with $dest_lang_code.

$mt->run_translators($expression, $src_lang_code, $dest_lang_code, %options)

Perform a translation of $expression from $src_lang_code language to $dest_lang_code language simultaneously on all enabled translators (plug-ins), which support this translation direction. The method returns true value on success, false on error. Use get_translation method for retrieving the results of particular translations.

The method sets the state of all plug-ins to "busy". See get_state method.

There are two ways of performing parallel run. If $options{tk_safe} is undefined or set to false value, then a child process is forked for every translator to be used and translate method is called. This is generally cleaner and more effective way of doing so then the one mentioned bellow. However, this causes trouble if the module is used in Perl/Tk applications.

If $options{tk_safe} is set to a true value, then a brand new child process is created for every plug-in to be used. For this plug-ins are required to implement get_trans_command method, which is expected to return a string containing a command, which can be run from a shell and provides appropriate functionality for the translation to be performed. This is an ugly hack necessary for making MetaTrans work in Perl/Tk applications. Hopefully this will be fixed in some of the future releases. See also MetaTrans::Base for more information on this.

Generally, if the plug-ins are only to be run with $options{tk_safe} set to false, they are not required to implement the get_trans_command method. Reversely, if the plug-ins are only to be run with $options{tk_safe} set to true, the are not required to implement the translate method. Plug-ins derrived from MetaTrans::Base implement both methods.

$mt->get_translation(%options)

Returns a translation returned by one of the running plug-ins (translators) as a string of following form:

expression = translation

The method blocks until there is a translation is available (until some of the running plug-ins is ready to provide an output). The order, in which the translations are returned depends on the order, in which the translators return their result and is therefore non-deterministic.

The behaviour of the method depends on the $options{return_translators} option. If undefined or set to a false value then every call returns one translation, undef value is returned to indicate the end.

If $options{return_value} is set to true value, the every call returns a (translation, translator) pair in an array, where the translator is the one, which returned the translation. (undef, translator) pair is returned to indicate that the translator finished running and. undef value is returned to indicate that no more translations are available.

The method also sets states of particular translators. See get_state method.

$mt->is_translation_available($timeout)

A non-blocking call, which returns a true value if next translation is already available. Otherwise it blocks for at most $timeout seconds and then returns false if a translation is still unavailable. However, if the $timeout is undefined then the method always blocks and never returns false value.

It is useful if you want to do something while waiting for the next translation. Example:

LOOP: while (1)
{
    # check every second
    until ($mt->is_translation_available(1.0))
    {
        last LOOP
            if &something_happened;
    }

    my $translation = $mt->get_translation;

    # ... do something with $translation ...
}

Note: To be more exact, the is_translation_available returns a true value if the get_translation_method has something to say. This must not necessairly be a next translation, but also an undef value or (<undef>, translator) pair.

$mt->stop_translators

Stop all running plug-ins. This simply kills all running child processes. The correspondent translators will end in the "busy" state.

Following methods set correspondent attributes of all plug-ins being used to specified values. See ATTRIBUTES section of MetaTrans::Base for more information.

$mt->set_timeout($timeout)
$mt->set_matching($type)
$mt->set_match_at_bounds($bool)

FUNCTIONS

sort_translations($expression, @translations)

Returns an array of translations sorted by relevance to the $expression. In addition, any duplicate information is removed.

BUGS

Please report any bugs or feature requests to bug-metatrans@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

AUTHOR

Jan Pomikalek, <xpomikal@fi.muni.cz>

COPYRIGHT & LICENSE

Copyright 2004 Jan Pomikalek, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

MetaTrans::Base, MetaTrans::Languages, MetaTrans::UltralinguaNet, Encode