Translator V2 to V3 Migration

The Microsoft Translator team has released Version 3 (V3) of the Translator. 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 into another script. For example, Arabic to 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. 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.

Move to JSON format

Microsoft Translator 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 selecting 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 End Points

Global

• api.cognitive.microsofttranslator.com

V3 API text translations methods

Languages

Translate

Transliterate

BreakSentence

Detect

Dictionary/lookup

Dictionary/example

Compatibility and customization

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

Translator Version 3

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

You are using Version 3 of the Translator if you are using the api.cognitive.microsofttranslator.com endpoint.

Translator Version 2

• Doesn't satisfy all ISO 20001,20018 and SOC 3 certification requirements.
• Doesn't 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 if you are using the api.microsofttranslator.com endpoint.

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

Links

• Microsoft Privacy Policy
• Microsoft Azure Legal Information
• Online Services Terms

Next steps