Quickstart: Use the Translator Text API to transliterate text

09/05/2019

20 minutes to read

In this article

In this quickstart, you'll learn how to transliterate (convert) text from one script to another using the Translator Text REST API. In the sample provided, Japanese is transliterated to use the Latin alphabet.

Select the C# language version

This quickstart requires C# 7.1 or later. There are a few ways to change the C# version for your project. In this guide, we'll show you how to adjust the transliterate-sample.csproj file. For all available options, such as changing the language in Visual Studio, see Select the C# language version.

Open your project, then open transliterate-sample.csproj. Make sure that LangVersion is set to 7.1 or later. If there isn't a property group for the language version, add these lines:

<PropertyGroup>
<LangVersion>7.1</LangVersion>
</PropertyGroup>

Add required namespaces to your project

The dotnet new console command that you ran earlier created a project, including Program.cs. This file is where you'll put your application code. Open Program.cs, and replace the existing using statements. These statements ensure that you have access to all the types required to build and run the sample app.

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
// Install Newtonsoft.Json with NuGet
using Newtonsoft.Json;

Create classes for the JSON response

Next, we're going to create a class that's used when deserializing the JSON response returned by the Translator Text API.

Create a function to transliterate text

Within the Program class, create an asynchronous function called TransliterateTextRequest(). This function takes four arguments: subscriptionKey, endpoint, route, and inputText.

static public async Task TransliterateTextRequest(string subscriptionKey, string endpoint, string route, string inputText)
{
/*
* The code for your call to the translation service will be added to this
* function in the next few sections.
*/
}

Serialize the translation request

Next, we need to create and serialize the JSON object that includes the text you want to translate. Keep in mind, you can pass more than one object in the body.

Put it all together

The last step is to call TransliterateTextRequest() in the Main function. In this sample, we're transliterating from Japanese to latin script. Locate static void Main(string[] args) and replace it with this code:

TRANSLATOR_TEXT_ENDPOINT - The global endpoint for Translator Text. Use https://api.cognitive.microsofttranslator.com/.

Initialize a project with Gradle

Let's start by creating a working directory for this project. From the command line (or terminal), run this command:

mkdir transliterate-sample
cd transliterate-sample

Next, you're going to initialize a Gradle project. This command will create essential build files for Gradle, most importantly, the build.gradle.kts, which is used at runtime to create and configure your application. Run this command from your working directory:

gradle init --type basic

When prompted to choose a DSL, select Kotlin.

Configure the build file

Locate build.gradle.kts and open it with your favorite IDE or text editor. Then copy in this build configuration:

Import required libraries

Define variables

First, you'll need to create a public class for your project:

public class Transliterate {
// All project code goes here...
}

Add these lines to the Transliterate class. First, the subscription key and endpoint are being read from environment variables. Then, you'll notice that along with the api-version, two additional parameters have been appended to the url. These parameters are used to set the input language, and the scripts for transliteration. In this sample, it's set to Japanese (jpan) and Latin (latn).

TRANSLATOR_TEXT_ENDPOINT - The global endpoint for Translator Text. Use https://api.cognitive.microsofttranslator.com/.

Create a project and import required modules

Create a new project using your favorite IDE or editor, or a new folder with a file named transliterate-text.py on your desktop. Then copy this code snippet into your project/file:

# -*- 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, endpoint, and path

This sample will try to read your Translator Text subscription key and endpoint from the environment variables: TRANSLATOR_TEXT_KEY and TRANSLATOR_TEXT_ENDPOINT. If you're not familiar with environment variables, you can set subscription_key and endpoint as a strings and comment out the conditional statements.

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.

If you haven't used these modules you'll need to install them before running your program. To install these packages, run: npm install request uuidv4.

These modules are required to construct the HTTP request, and create a unique identifier for the 'X-ClientTraceId' header.

Set the subscription key and endpoint

This sample will try to read your Translator Text subscription key and endpoint from these environment variables: TRANSLATOR_TEXT_SUBSCRIPTION_KEY and TRANSLATOR_TEXT_ENDPOINT. If you're not familiar with environment variables, you can set subscriptionKey and endpoint as strings and comment out the conditional statements.

Configure the request

The request() method, made available through the request module, allows us to pass the HTTP method, URL, request params, headers, and the JSON body as an options object. In this code snippet, we'll configure the request:

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.

If you are using a Cognitive Services multi-service subscription, you must also include the Ocp-Apim-Subscription-Region in your request headers.

In this sample, we're defining the HTTP request in the options object. However, the request module also supports convenience methods, like .post and .get. For more information, see convenience methods.

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:

node transliterate-text.js

If you'd like to compare your code against ours, the complete sample is available on GitHub.

Sample response

[
{
"script": "latn",
"text": "konnichiwa"
}
]

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

Take a look at the API reference to understand everything you can do with the Translator Text API.

Create the main function

This sample will try to read your Translator Text subscription key and endpoint from these environment variables: TRANSLATOR_TEXT_SUBSCRIPTION_KEY and TRANSLATOR_TEXT_ENDPOINT. If you're not familiar with environment variables, you can set subscriptionKey and endpoint as strings and comment out the conditional statements.

Create a function to transliterate text

Let's create a function to transliterate text. This function will take a single argument, your Translator Text subscription key.

func transliterate(subscriptionKey string, uri string) {
/*
* In the next few sections, we'll add code to this
* function to make a request and handle the response.
*/
}

Next, let's construct the URL. The URL is built using the Parse() and Query() methods. You'll notice that parameters are added with the Add() method. In this sample, we're transliterating from Japanese to the Latin alphabet.