Translator V2 to V3 Migration

Version 3 (V3) of the Translator service is generally available. The 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 the service doesn't save text submitted to the V3 API.
• JSON - XML replaces 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 is added to the API. This method includes lookup and examples.
• Transliteration - A transliterate method is added to the API. This method converts 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 are added to the translate method to support some of the features that were in the V2 API as separate methods. An example is TranslateArray.
• Speech 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 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 Translation V2 accepted and returned data in XML format. In V3, all data sent and received using the API is in JSON format. XML is no longer accepted or returned in V3.

This change affects 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 doesn't require authentication; by selecting the following link you can see all the language information for V3 in JSON:

https://api.translator.azure.cn/languages?api-version=3.0&scope=translation,dictionary,transliteration

Authentication Key

The authentication key used for V2 is accepted for V3. You don't need to get a new subscription. You can mix V2 and V3 in your apps during the yearlong migration period, making it easier for you to release new versions while you migrate 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 counted as 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.translator.azure.cn

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 can't be used with the Microsoft Translator Hub. The Translator Hub only supports legacy statistical machine translation.

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

Version	Endpoint	GDPR Processor Compliance	Use Translator Hub	Use Custom Translator (Preview)
Translator Version 2	api.translator.azure.cn	No	Yes	No
Translator Version 3	api.translator.azure.cn	Yes	No	Yes

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 customized with Custom Translator (Preview), the new Translator neural machine translation (NMT) customization feature.
• It doesn't provide access to custom translation systems created using the Microsoft Translator Hub.

You're using Version 3 of the Translator if you're using the api.translator.azure.cn 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 customized with the Translator customization feature.
• Does provide access to custom translation systems created using the Microsoft Translator Hub.
• Uses 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
• Azure Legal Information
• Online Services Terms

Next steps