Translator 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. V2 was retired on May 24, 2021.
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
tolanguages for translation in a single request. For example, a single request can befromEnglish andtoGerman, Spanish and Japanese, or any other group of languages. - Bilingual dictionary - A bilingual dictionary method is added to the API. This method includes
lookupandexamples. - 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
languagesmethod delivers language information, in JSON format, for use with thetranslate,dictionary, andtransliteratemethods. - New to Translate - New capabilities are added to the
translatemethod 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:
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.cognitive.microsofttranslator.com
V3 API text translations methods
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 can't 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 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.microsofttranslator.com | No | Yes | No |
| Translator Version 3 | api.cognitive.microsofttranslator.com | 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.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 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.