Azure TextTranslation REST client library for JavaScript
Azure text translation is a cloud-based REST API provided by the Azure Translator service. It utilizes neural machine translation technology to deliver precise, contextually relevant, and semantically accurate real-time text translations across all supported languages.
The client library offers several key functionalities:
-
Retrieve the list of languages supported for translation and transliteration operations, as well as LLM models available for translations.
-
Perform deterministic text translation from a specified source language to a target language, with configurable parameters to ensure precision and maintain contextual integrity.
-
Execute transliteration by converting text from the original script to an alternative script representation.
-
Use LLM models to produce translation output variants that are tone-specific and gender-aware.
Please rely heavily on our REST client docs to use this library
Key links:
Getting started
Currently supported environments
- LTS versions of Node.js
- Latest versions of Edge, Chrome, Safari and Firefox
Prerequisites
- You must have an Azure subscription to use this package.
- An existing Translator service or Cognitive Services resource.
Install the @azure-rest/ai-translation-text package
Install the Azure TextTranslation REST client REST client library for JavaScript with npm:
npm install @azure-rest/ai-translation-text
Create a Translator service resource
You can create a Translator resource following Create a Translator resource.
Browser support
JavaScript Bundle
To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our bundling documentation.
Authenticate the client
Interaction with the service using the client library begins with creating an instance of the TextTranslationClient class. You will need an API key or TokenCredential to instantiate a client object. For more information regarding authenticating with cognitive services, see Authenticate requests to Translator Service.
Get an API key
You can get the endpoint, API key and Region from the Cognitive Services resource or Translator service resource information in the Azure Portal.
Alternatively, use the Azure CLI snippet below to get the API key from the Translator service resource.
az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>
Create a TextTranslationClient using an Azure Active Directory credential
To use an Azure Active Directory (AAD) token credential, provide an instance of the desired credential type obtained from the @azure/identity library.
To authenticate with AAD, you must first npm install @azure/identity
After setup, you can choose which type of credential from @azure/identity to use.
As an example, DefaultAzureCredential
can be used to authenticate the client.
Create a TextTranslationClient using an API key and Region credential
Once you have the value for the API key and Region, create an TranslatorCredential.
With the value of the TranslatorCredential you can create the TextTranslationClient:
import TextTranslationClient, { TranslatorCredential } from "@azure-rest/ai-translation-text";
const endpoint = "https://api.cognitive.microsofttranslator.com";
const key = "YOUR_SUBSCRIPTION_KEY";
const region = "westus";
const credential: TranslatorCredential = {
key,
region,
};
const translationClient = TextTranslationClient(endpoint, credential);
Examples
The following section provides several code snippets using the client created above, and covers the main features present in this client library.
Get Supported Languages
Gets the set of languages currently supported by other operations of the Translator.
import TextTranslationClient, {
TranslatorCredential,
isUnexpected,
} from "@azure-rest/ai-translation-text";
const endpoint = "https://api.cognitive.microsofttranslator.com";
const key = "YOUR_SUBSCRIPTION_KEY";
const region = "westus";
const credential: TranslatorCredential = {
key,
region,
};
const translationClient = TextTranslationClient(endpoint, credential);
const langResponse = await translationClient.path("/languages").get();
if (isUnexpected(langResponse)) {
throw langResponse.body.error;
}
const languages = langResponse.body;
if (languages.translation) {
console.log("Translated languages:");
for (const [key, translationLanguage] of Object.entries(languages.translation)) {
console.log(`${key} -- name: ${translationLanguage.name} (${translationLanguage.nativeName})`);
}
}
if (languages.transliteration) {
console.log("Transliteration languages:");
for (const [key, transliterationLanguage] of Object.entries(languages.transliteration)) {
console.log(
`${key} -- name: ${transliterationLanguage.name} (${transliterationLanguage.nativeName})`,
);
}
}
if (languages.models) {
console.log("Available LLM Models:");
for (const model in languages.models) {
console.log(model);
}
}
Please refer to the service documentation for a conceptual discussion of languages.
Translate
Renders single source-language text to multiple target-language texts with a single request.
import TextTranslationClient, {
TranslatorCredential,
isUnexpected,
} from "@azure-rest/ai-translation-text";
const endpoint = "https://api.cognitive.microsofttranslator.com";
const key = "YOUR_SUBSCRIPTION_KEY";
const region = "westus";
const credential: TranslatorCredential = {
key,
region,
};
const translationClient = TextTranslationClient(endpoint, credential);
const input = {
text: "This is a test.",
targets: [{ language: "cs" }],
language: "en",
};
const translateResponse = await translationClient.path("/translate").post({
body: { inputs: [input] },
});
if (isUnexpected(translateResponse)) {
throw translateResponse.body.error;
}
const translations = translateResponse.body.value;
for (const translation of translations) {
console.log(
`Text was translated to: '${translation?.translations[0]?.language}' and the result is: '${translation?.translations[0]?.text}'.`,
);
}
Please refer to the service documentation for a conceptual discussion of translate.
Transliterate
Converts characters or letters of a source language to the corresponding characters or letters of a target language.
import TextTranslationClient, {
TranslatorCredential,
isUnexpected,
} from "@azure-rest/ai-translation-text";
const endpoint = "https://api.cognitive.microsofttranslator.com";
const key = "YOUR_SUBSCRIPTION_KEY";
const region = "westus";
const credential: TranslatorCredential = {
key,
region,
};
const translationClient = TextTranslationClient(endpoint, credential);
const inputText = [{ text: "这是个测试。" }];
const parameters = {
language: "zh-Hans",
fromScript: "Hans",
toScript: "Latn",
};
const transliterateResponse = await translationClient.path("/transliterate").post({
body: { inputs: inputText },
queryParameters: parameters,
});
if (isUnexpected(transliterateResponse)) {
throw transliterateResponse.body.error;
}
const transliterations = transliterateResponse.body.value;
for (const transliteration of transliterations) {
console.log(
`Input text was transliterated to '${transliteration?.script}' script. Transliterated text: '${transliteration?.text}'.`,
);
}
Please refer to the service documentation for a conceptual discussion of transliterate.
Troubleshooting
When you interact with the Translator Service using the TextTranslator client library, errors returned by the Translator service correspond to the same HTTP status codes returned for REST API requests.
For example, if you submit a translation request without a target translate language, a 400 error is returned, indicating "Bad Request".
Logging
Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.