NAME

I22r::Translate::Microsoft - Microsoft Translator backend for I22r::Translate framework

VERSION

Version 0.94

SYNOPSIS

    I22r::Translate->config(
        'I22r::Translate::Microsoft' => {
            ENABLED => 1,
            CLIENT_ID => 'your_Microsoft/Azure_client_id',
            SECRET => 'your_Microsoft/Azure_secret'
        }
    );

    $translation = I22r::Translate->translate_string(
        src => 'en', dest => 'es', text => 'hello world',
        quality => { 'I22r::Translate::Microsoft' => 2.0 } );

DESCRIPTION

Invokes Microsoft's translation webservice to translate content from one language to another.

CONFIG

You instruct the I22r::Translate package to use the Microsoft backend by passing a key-value pair to the I22r::Translate::config method where the key is the string "I22r::Translate::Microsoft" and the value is a hash reference with at least the following key-value pairs:

ENABLED => 0 | 1

Must be set to a true value for the Microsoft backend to function.

CLIENT_ID => userid

Required Windows Azure Marketplace client ID for accessing the Microsoft Translator API. See "CREDENTIALS", below.

SECRET => 44-character string

Required Windows Azure Marketplace "client secret" for accessing the Microsoft Translator API. See "CREDENTIALS", below.

timeout => integer

Stops a translation job after a certain number of seconds have passed. Optional. Any translations that were completed before the timeout will still be returned.

callback => code reference or function name

A function to be invoked when the Microsoft backend obtains a translation result. The function will be called with two arguments: the request object that is handling the translation, and a hash reference containing the fields and values for the new translation result.

You can have separate callbacks in the global configuration, for each backend, and for the current request.

filter => array reference

List of filters to use (see I22r::Translate::Filter) when sending text to the Microsoft Translate webservice.

CREDENTIALS

This package interacts with the Microsoft Translator API, which requires some you/us to provide a "client id" and "client secret" to access Microsoft's data services. As of October 2012, here are the steps you need to take to get those credentials. (If these steps don't work anymore, and you do figure out what steps you need to do, let me know or file a bug report and I'll update this document.

1. If you don't have a Windows Live ID , sign up for one at https://signup.live.com/signup.aspx?lic=1
2. Visit https://datamarket.azure.com/dataset/bing/microsofttranslator. Register for a "Windows Azure Marketplace" account.
3. Choose a Microsoft Translator data plan. One of the available plans is a free option for 2,000,000 characters/month.
4. Now you have to "register an application". Visit https://datamarket.azure.com/developer/applications and hit the big green REGISTER button.
5. Choose any "Client ID" and "Name" for your application. The "URI" is also a required field, but the translator API doesn't use it, so you can put whatever you like in that field, too.

   Make a note of the "Client ID" value that you entered and the "Client secret" value that Microsoft provided. You will have to provide these values to the I22r::Translate::Microsoft backend configuration with the CLIENT_ID and SECRET keys.

   Example: If your application registration screen looks like:

       * Client ID         angus
       * Name              The Beefinator
       * Client secret     ykiDjfQ9lztW/oFUC4t2ciPWH2nJS88FqXcQbs/Z9Y=7
       * Redirect URI      https://ilikebeef.com/
         Description       The multilingual Beefinator site

   Then you would configure the Microsoft backend with

       I22r::Translate->config(
           'I22r::Translate::Microsoft' => {
               ENABLED => 1,
               CLIENT_ID => "angus",
               SECRET => "ykiDjfQ9lztW/oFUC4t2ciPWH2nJS88FqXcQbs/Z9Y=7"
           } );

   (these are not real credentials).

AUTHOR

Marty O'Brien, <mob at cpan.org>

BUGS

Please report any bugs or feature requests to bug-i22r-translate-microsoft at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=I22r-Translate-Microsoft. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc I22r::Translate::Microsoft

You can also look for information at:

• RT: CPAN's request tracker (report bugs here)

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=I22r-Translate-Microsoft

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/I22r-Translate-Microsoft

• CPAN Ratings

  http://cpanratings.perl.org/d/I22r-Translate-Microsoft

• Search CPAN

  http://search.cpan.org/dist/I22r-Translate-Microsoft/

SUBROUTINES/METHODS

There should be no need to use the methods of this package directly. See I22r::Translate::Backend and I22r::Translate.

SEE ALSO

I22r::Translate

LICENSE AND COPYRIGHT

Copyright 2012-2013 Marty O'Brien.

This program 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/ for more information.