Translator Text API V2 to V3 Migration

Note

V2 was deprecated on April 30, 2018. Please migrate your applications to V3 in order to take advantage of new functionality available exclusively in V3.

The Microsoft Translator Hub will be retired on May 17, 2019. View important migration information and dates.

The Microsoft Translator team has released Version 3 (V3) of the Translator Text API. This release includes new features, deprecated methods and a new format for sending to, and receiving data from the Microsoft Translator Service. This document provides information for changing applications to use V3.

The end of this document contains helpful links for you to learn more.

Summary of features

  • No Trace - In V3 No-Trace applies to all pricing tiers in the Azure portal. This feature means that no text submitted to the V3 API, will be saved by Microsoft.
  • JSON - XML is replaced by JSON. All data sent to the service and received from the service is in JSON format.
  • Multiple target languages in a single request - The Translate method accepts multiple ‘to’ languages for translation in a single request. For example, a single request can be ‘from’ English and ‘to’ German, Spanish and Japanese, or any other group of languages.
  • Bilingual dictionary - A bilingual dictionary method has been added to the API. This method includes ‘lookup’ and ‘examples’.
  • Transliterate - A transliterate method has been added to the API. This method will convert words and sentences in one script (E.g. Arabic) into another script (E.g. Latin).
  • Languages - A new ‘languages’ method delivers language information, in JSON format, for use with the ‘translate’, ‘dictionary’, and ‘transliterate’ methods.
  • New to Translate - New capabilities have been added to the ‘translate’ method to support some of the features that were in the V2 API as separate methods. An example is TranslateArray.
  • Speak method - Text to speech functionality is no longer supported in the Microsoft Translator API. Text to speech functionality is available in Microsoft Speech Service.

The following list of V2 and V3 methods identifies the V3 methods and APIs that will provide the functionality that came with V2.

V2 API Method V3 API Compatibility
Translate Translate
TranslateArray Translate
GetLanguageNames Languages
GetLanguagesForTranslate Languages
GetLanguagesForSpeak Microsoft Speech Service
Speak Microsoft Speech Service
Detect Detect
DetectArray Detect
AddTranslation Feature is no longer supported
AddTranslationArray Feature is no longer supported
BreakSentences BreakSentence
GetTranslations Feature is no longer supported
GetTranslationsArray Feature is no longer supported

Move to JSON format

Microsoft Translator Text Translation V2 accepted and returned data in XML format. In V3 all data sent and received using the API is in JSON format. XML will no longer be accepted or returned in V3.

This change will affect several aspects of an application written for the V2 Text Translation API. As an example: The Languages API returns language information for text translation, transliteration, and the two dictionary methods. You can request all language information for all methods in one call or request them individually.

The languages method does not require authentication; by clicking on the following link you can see all the language information for V3 in JSON:

https://api.cognitive.microsofttranslator.com/languages?api-version=3.0&scope=translation,dictionary,transliteration

Authentication Key

The authentication key you are using for V2 will be accepted for V3. You will not need to get a new subscription. You will be able to mix V2 and V3 in your apps during the yearlong migration period, making it easier for you to release new versions while you are still migrating from V2-XML to V3-JSON.

Pricing Model

Microsoft Translator V3 is priced in the same way V2 was priced; per character, including spaces. The new features in V3 make some changes in what characters are counted for billing.

V3 Method Characters Counted for Billing
Languages No characters submitted, none counted, no charge.
Translate Count is based on how many characters are submitted for translation, and how many languages the characters are translated into. 50 characters submitted, and 5 languages requested will be 50x5.
Transliterate Number of characters submitted for transliteration are counted.
Dictionary lookup & example Number of characters submitted for Dictionary lookup and examples are counted.
BreakSentence No Charge.
Detect No Charge.

V3 End Points

Global

  • api.cognitive.microsofttranslator.com

V3 API text translations methods

Languages

Translate

Transliterate

BreakSentence

Detect

Dictionary/lookup

Dictionary/example

Compatibility and customization

Note

The Microsoft Translator Hub will be retired on May 17, 2019. View important migration information and dates.

Microsoft Translator V3 uses neural machine translation by default. As such, it cannot be used with the Microsoft Translator Hub. The Translator Hub only supports legacy statistical machine translation. Customization for neural translation is now available using the Custom Translator. Learn more about customizing neural machine translation

Neural translation with the V3 text API does not support the use of standard categories (SMT, speech, tech, generalnn).

Endpoint GDPR Processor Compliance Use Translator Hub Use Custom Translator (Preview)
Translator Text API Version 2 api.microsofttranslator.com No Yes No
Translator Text API Version 3 api.cognitive.microsofttranslator.com Yes No Yes

Translator Text API Version 3

  • Is generally available and fully supported.
  • Is GDPR compliant as a processor and satisfies all ISO 20001 and 20018 as well as SOC 3 certification requirements.
  • Allows you to invoke the neural network translation systems you have customized with Custom Translator (Preview), the new Translator NMT customization feature.
  • Does not provide access to custom translation systems created using the Microsoft Translator Hub.

You are using Version 3 of the Translator Text API If you are using the api.cognitive.microsofttranslator.com endpoint.

Translator Text API Version 2

  • Does not satisfy all ISO 20001,20018 and SOC 3 certification requirements.
  • Does not allow you to invoke the neural network translation systems you have customized with the Translator customization feature.
  • Provides access to custom translation systems created using the Microsoft Translator Hub.
  • You are using Version 2 of the Translator Text API If you are using the api.microsofttranslator.com endpoint.

No version of the Translator API creates a record of your translations. Your translations are never shared with anyone. More information on the Translator No-Trace webpage.

Next steps