NAME

WWW::Google::Translate - Perl interface for the Google Translate API

SYNOPSIS

Use Case 1

use WWW::Google::Translate;

my $wgt = WWW::Google::Translate->new(
    {   key            => '<Your API key here>',
        default_source => 'en',   # optional
        default_target => 'ja',   # optional
    }
);

my $r = $wgt->translate( { q => 'My hovercraft is full of eels' } );

for my $trans_rh (@{ $r->{data}->{translations} })
{
    print $trans_rh->{translatedText}, "\n";
}

Use Case 2

use WWW::Google::Translate;

my $wgt = WWW::Google::Translate->new( { key => '<Your API key here>' } );

my $r = $wgt->translate(
    {   q           => 'My hovercraft is full of eels',
        source      => 'en',
        target      => 'ja',
        model       => 'nmt',
        format      => 'text',
        prettyprint => 1,
    }
);

for my $trans_rh (@{ $r->{data}->{translations} })
{
    print $trans_rh->{translatedText}, "\n";
}

Use Case 3

use WWW::Google::Translate;

my $wgt = WWW::Google::Translate->new( { key => '<Your API key here>' } );

my $r = $wgt->translate(
    {   q      => 'My hovercraft is full of eels',
        target => 'ja',
    }
);

for my $trans_rh ( @{ $r->{data}->{translations} } )
{
    print 'detected language: ', $trans_rh->{detectedSourceLanguage}, "\n";
    print $trans_rh->{translatedText}, "\n";
}

Language Detection

use WWW::Google::Translate;

my $wgt = WWW::Google::Translate->new( { key => '<Your API key here>' } );

my $r = $wgt->detect( { q => 'My hovercraft is full of eels' } );

my $lang = $r->{data}->{detections}->[0]->[0]->{language};

DESCRIPTION

This module provides a convenient interface for using the Google Translate API.

See: https://cloud.google.com/translate/docs/getting-started

METHODS

new

The constructor expects a hash ref with the following parameters:

key

Your API key. The key must be configured to be used with the machine you're running your program on.

default_source

This is the source language for any text you'll be submitting with the translate method. This is optional if you would rather supply the 'source' parameter to the translate method.

default_target

This is the target language for any text you'll be submitting with the translate method. This is optional if you would rather supply the 'target' parameter to the translate method.

data_format

This is either 'json' or 'perl'. If you indicate 'json' then you'll get the raw JSON as given by the remote API. Otherwise, the JSON::from_json function is used to transform the result to a perl data structure. Default is 'perl'.

format

Indicate either 'text' or 'html' as the format of the source text. This module will attempt to auto-detect if omitted.

model

Indicate either 'nmt' (for Neural Machine Translation) or 'base' (for Phrase-Based Machine Translation).

See: https://cloud.google.com/translate/docs/translating-text#specifying_a_model

prettyprint

Indicate a boolean for pretty formatted result. Default is true.

timeout

Use this parameter to control the timeout period given to the underlying LWP::UserAgent object. Default is 60 seconds.

agent

Use this to set the user-agent string used by your program when sending HTTP requests to the remote API.

force_post

The API docs state that 5K is the size limit per translate request. However the GET method limits the size to 2K. This module will force a POST type request if the size of your data is more than 2K. However, overvation suggests that your mileage may vary. If you find you're getting 414 Request-URI Too Large errors then you can try setting this option to 1.

headers

You can send custom headers in the HTTP requests to the API.

my $wgt = WWW::Google::Translate->new(
    {   key              => '<Your API key here>',
        default_source   => 'en',
        default_target   => 'ja',
        headers          => {
            Agent => 'My Translation App',
            Words => 'Play us out',
        },
    }
);

cache_file

Use this parameter to supply a filename for where you'd like your translations to be cached. This is useful if you're translating a lot of material where there may be repeated input text.

my $wgt = WWW::Google::Translate->new(
    {   key              => '<Your API key here>',
        default_source   => 'en',
        default_target   => 'ja',
        cache_file       => '/tmp/translate-cache.dat',
    }
);

If the translation can be fetched from this cache then there will be no request to the translate API. Depending on your application, this can increase performance and reduce your billing.

detect

Use this to auto-detect the language of a given chunk of text. Expects a hash ref with a 'q' paramter. Returns the data structure returned from the remote API.

my $d_rh        = $wgt->detect( { q => $text } );
my $language    = $d_rh->{data}->{detections}->[0]->[0]->{language};
my $is_reliable = $d_rh->{data}->{detections}->[0]->[0]->{isReliable};
my $confidence  = $d_rh->{data}->{detections}->[0]->[0]->{confidence};

Note: You can get the benefit of auto-detected source language by simply omitting the 'source' and 'default_source' parameters for translate and the contructor.

translate

Use this to translate a given chunk of text. Expects a hash ref with a 'q' paramter. You may also supply 'source' and 'target' parameters. Returns the data structure returned from the remote API.

my $d_rh = $wgt->translate( { q => $text } );
$text    = $d_rh->{data}->{translations}->[0]->{translatedText};
$lang    = $d_rh->{data}->{translations}->[0]->{detectedSourceLanguage};

The 'detectedSourceLanguage' will be included if you omit the 'source' parameter to translate (and also the default_source for the constructor).

AUTHOR

Dylan Doxey, <dylan@cpan.org>

The author of this module is not affiliated with Google.

ACKNOWLEDGEMENTS

Thanks to Sebastian Schleussner for submitting improvements and helpful feedback.

COPYRIGHT AND LICENSE

Copyright (C) 2017 by Dylan Doxey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.4 or, at your option, any later version of Perl 5 you may have available.