pymstranslator 0.0.1

==============
PyMSTranslator
==============

PyMSTranslator is the Python client for `Microsoft(r) Translator`_ service.
It's ultimate goal is to provide full implementation of the entire MS
Translator service API. The immediate goal is to provide basic translation
functionality.

Getting started
===============

Before you can get started, you will need to obtain the API key (Microsoft(r)
Live account required).

Subscribe to the Microsoft Translator API at Azure Marketplace, and obtain the
API key. More iformation can be found `on the Microsoft's site`_.

The service is free up to 2M characters per month.

Installing and using PyMSTranslator
===================================

Install from pip::

pip install pymstranslator

Basic usage
===========

Before you can use the Microsoft Translator API, you need to register your app.
Once you do that, you will receive client ID and client secret. Note these
down.

Creating the access key
-----------------------

Once in your application's initialization code, you must create the access key
(access token). This is best done in such a way that the access key is always
available to parts of your application that may require the key. Once created,
the will be valid for 10 minutes and is cached to avoid repeated requests to
the authorization server. Here is an example::

>>> from mstranslator import MSTranslatorAccessKey
>>> key = MSTranslatorAccessKey(client_id, client_secret)

In Django, for example, you may create the key in the settings module, and make
it available as a configuration setting::

# setup.py
import os
CLIENT_ID = os.environ.get('TRANSLATOR_ID')
CLIENT_SECRET = os.environ.get('TRANSLATOR_SECRET')
MS_TRANSLATOR_KEY = MSTranslatorAccessKey(CLIENT_ID, CLIENT_SECRET)

# somewhere in your view
from django.conf import settings
key = settings.MS_TRANSLATOR_KEY

The key object has a ``get_key`` method which returns the cached key if it has
not expired yet, shortening the response time. This method is used by the
client object to retrieve the cached key, so you don't need to worry about the
internal implementation.

Creating the Microsoft Translator client object
-----------------------------------------------

The client object is crated using the key crated in the `Creating the access
key`_ section::

>>> from mstranslator import MSTranslator
>>> translator = MSTranslator(key)

The client object currently only has one useful method, and that is
``translate``. To translate a string, call the method like so::

>>> translator.translate(text='Si vous plais', tfrom='fr', to='en')
"If you'd like"

Microsoft Translator API coverage
=================================

Currently, only the ``Translate`` method has been implemented. The goal for 1.0
release is to include all of the Microsoft Translator API v2.

For the most part, the API of Microsoft Translator methods should be almost
identical in PyMSTranslator except for a few details:

+ Method names are always lower-case using underscores to separate words (e.g.,
``TranslateArray`` becomes ``translate_array``)
+ Same applies to parameters (e.g., ``contentType`` becomes ``content_type``)
+ Parameter names that match Python built-in names are prefixed with ``t``
(e.g., ``from`` becomes ``tfrom``, ``format`` becomes ``tformat``)

Caching
=======

There is currently no caching of the translations. Caching mechanism is planned
for 1.0 release, though, with an interface compatible with the Django's caching
mechanism. For now, caching must be done separately.

Reporting bugs
==============

Bugs can be reported to the BitBucket `issue tracker`_.

.. _Microsoft(r) Translator: http://www.microsofttranslator.com/dev/
.. _on the Microsoft's site: http://www.microsoft.com/web/post/using-the-free-bing-translation-apis
.. _issue trakcer: https://bitbucket.org/monwara/pymstranslator/issues