Package: pymstranslator
==============PyMSTranslator==============PyMSTranslator is the Python client for `Microsoft(r) Translator`_ service.It's ultimate goal is to provide full implementation of the entire MSTranslator service API. The immediate goal is to provide basic translationfunctionality.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 theAPI 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 pymstranslatorBasic 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 thesedown.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 alwaysavailable 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 tothe 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 makeit available as a configuration setting::# setup.pyimport osCLIENT_ID = os.environ.get('TRANSLATOR_ID')CLIENT_SECRET = os.environ.get('TRANSLATOR_SECRET')MS_TRANSLATOR_KEY = MSTranslatorAccessKey(CLIENT_ID, CLIENT_SECRET)# somewhere in your viewfrom django.conf import settingskey = settings.MS_TRANSLATOR_KEYThe key object has a ``get_key`` method which returns the cached key if it hasnot expired yet, shortening the response time. This method is used by theclient object to retrieve the cached key, so you don't need to worry about theinternal implementation.Creating the Microsoft Translator client object-----------------------------------------------The client object is crated using the key crated in the `Creating the accesskey`_ 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.0release is to include all of the Microsoft Translator API v2.For the most part, the API of Microsoft Translator methods should be almostidentical 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 plannedfor 1.0 release, though, with an interface compatible with the Django's cachingmechanism. 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