Quickstart: Look up words with bilingual dictionary using Python
In this quickstart, you'll learn how to find alternate translations and usage examples for a specified text using Python and the Translator Text REST API.
This quickstart requires an Azure Cognitive Services account with a Translator Text resource. If you don't have an account, you can use the free trial to get a subscription key.
Prerequisites
This quickstart requires:
- Python 2.7.x or 3.x
- An Azure subscription key for Translator Text
Create a project and import required modules
Create a new Python project using your favorite IDE or editor. Then copy this code snippet into your project in a file named dictionary-lookup.py
.
# -*- coding: utf-8 -*-
import os, requests, uuid, json
Note
If you haven't used these modules you'll need to install them before running your program. To install these packages, run: pip install requests uuid
.
The first comment tells your Python interpreter to use UTF-8 encoding. Then required modules are imported to read your subscription key from an environment variable, construct the http request, create a unique identifier, and handle the JSON response returned by the Translator Text API.
Set the subscription key, base url, and path
This sample will try to read your Translator Text subscription key from the environment variable TRANSLATOR_TEXT_KEY
. If you're not familiar with environment variables, you can set subscriptionKey
as a string and comment out the conditional statement.
Copy this code into your project:
# Checks to see if the Translator Text subscription key is available
# as an environment variable. If you are setting your subscription key as a
# string, then comment these lines out.
if 'TRANSLATOR_TEXT_KEY' in os.environ:
subscriptionKey = os.environ['TRANSLATOR_TEXT_KEY']
else:
print('Environment variable for TRANSLATOR_TEXT_KEY is not set.')
exit()
# If you want to set your subscription key as a string, uncomment the line
# below and add your subscription key.
#subscriptionKey = 'put_your_key_here'
The Translator Text global endpoint is set as the base_url
. path
sets the dictionary/lookup
route and identifies that we want to hit version 3 of the API.
The params
are used to set the source and output languages. In this sample we're using English and Spanish: en
and es
.
Note
For more information about endpoints, routes, and request parameters, see Translator Text API 3.0: Dictionary Lookup.
base_url = 'https://api.cognitive.microsofttranslator.com'
path = '/dictionary/lookup?api-version=3.0'
params = '&from=en&to=es';
constructed_url = base_url + path + params
Add headers
The easiest way to authenticate a request is to pass in your subscription key as an
Ocp-Apim-Subscription-Key
header, which is what we use in this sample. As an alternative, you can exchange your subscription key for an access token, and pass the access token along as an Authorization
header to validate your request. For more information, see Authentication.
Copy this code snippet into your project:
headers = {
'Ocp-Apim-Subscription-Key': subscriptionKey,
'Content-type': 'application/json',
'X-ClientTraceId': str(uuid.uuid4())
}
Create a request to find alternate translations
Define the string (or strings) that you want to find translations for:
# You can pass more than one object in body.
body = [{
'text': 'Elephants'
}]
Next, we'll create a POST request using the requests
module. It takes three arguments: the concatenated URL, the request headers, and the request body:
request = requests.post(constructed_url, headers=headers, json=body)
response = request.json()
Print the response
The last step is to print the results. This code snippet prettifies the results by sorting the keys, setting indentation, and declaring item and key separators.
print(json.dumps(response, sort_keys=True, indent=4, ensure_ascii=False, separators=(',', ': ')))
Put it all together
That's it, you've put together a simple program that will call the Translator Text API and return a JSON response. Now it's time to run your program:
python dictionary-lookup.py
If you'd like to compare your code against ours, the complete sample is available on GitHub.
Sample response
[
{
"displaySource": "elephants",
"normalizedSource": "elephants",
"translations": [
{
"backTranslations": [
{
"displayText": "elephants",
"frequencyCount": 1207,
"normalizedText": "elephants",
"numExamples": 5
}
],
"confidence": 1.0,
"displayTarget": "elefantes",
"normalizedTarget": "elefantes",
"posTag": "NOUN",
"prefixWord": ""
}
]
}
]
Clean up resources
If you've hardcoded your subscription key into your program, make sure to remove the subscription key when you're finished with this quickstart.
Next steps
See also
Learn how to use the Translator Text API to:
Feedback
We'd love to hear your thoughts. Choose the type you'd like to provide:
Our feedback system is built on GitHub Issues. Read more on our blog.
Loading feedback...