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:

import os
CLIENT_ID = os.environ.get('TRANSLATOR_ID')

# 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)


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`_.