AJAX-Microsoft Translator V2 必应在线翻译API.pdf

AJAX Microsoft Translator V2 To start using the AJAX API for the Microsoft Translator service all you need to do is to direct an ajax call to the appropiate method and register a callback function and that s it the translator api will handle the heavy lifting and pass the results of the method back to a registered callback function and part of this heavy lifting is the encodeURIcomponent function which is provided to escape utf characters that may be present in the strings that we pass to the translator service How this all works is to dynamically register a html script element to the tag of the page via acessing the DOM Within this script is contained the call to the translator ajax service api as well as a callback function Once the AJAX call to the Microsoft Translator API is complete the API will return to the callback handler function that we have previously nominated Public Methods Name Description Microsoft Translator AddTranslation Method Adds a translation to the translation memory Microsoft Translator AddTranslationArray Method Adds an array of translations to the translation memory Microsoft Translator BreakSentences Method Returns an array of sentence lengths for each sentence of the given text Microsoft Translator Detect Method Detects the language of a selection of text Microsoft Translator DetectArray Method Detects the language of an array of strings Microsoft Translator GetAppIdToken Method Returns a tokenized AppID which can be used as AppID parameter in any method Microsoft Translator GetLanguageNames Method Obtains a list of the languages supported by the Translator Service Microsoft Translator GetLanguagesForSpeak Method Obtains a list of the language codes supported by the Translator Service for speech synthesis Microsoft Translator GetLanguagesForTranslate Method Obtains a list of the language codes supported by the Translator Service Microsoft Translator GetTranslations Method Returns an array of alternative translations of the given text Microsoft Translator GetTranslationsArray Method Returns an array of alternative translations of the passed array of text Microsoft Translator Speak Method Returns a string with a URL to a wave stream of the passed in text in desired language Microsoft Translator Translate Method Converts a text string from one language to another Microsoft Translator TranslateArray Method Translates an array of texts into another language AddTranslation Method Microsoft Translator V2 Adds a translation to the translation memory Syntax URI Parameters Parameter Description appId A string containing the Bing AppID originalText A string containing the text to translate from The string has a maximum length of 1000 characters translatedText A string containing translated text in the target language The string has a maximum length of 1000 characters from A string continaing the language code of the source language Must be a valid culture name to A string containing the language code of the target language Must be a valid culture name rating Optional An int representing the quality rating for this string Value between 10 and 10 Defaults to 1 contentType The format of the text being translated The supported formats are text plain and text html Any HTML needs to be well formed category Optional A string containing the category domain of the translation Defaults to general user A string used to track the originator of the submission uri Optional A string containing the content location of this translation Example JavaScript var originalText encodeURIComponent This text is being submitted through this method var translatedText encodeURIComponent Dieser Text wird durch diese Methode vorgelegt function addTranslation var s document createElement script s src document getElementsByTagName head 0 appendChild s AddTranslationArray Method Microsoft Translator V2 Adds an array of translations to add translation memory This is an array version of AddTranslation Syntax URI Parameters Parameter Description appId A string containing the Bing AppID translations An array of translations to add to translation memory Each translation must contain originalText translatedText rating There can only be a maximum number of 100 translations in the array and each string in the contained objects has a limit of 1000 characters from A string continaing the language code of the source language Must be a valid culture name to A string containing the language code of the target language Must be a valid culture name options A set of options TranslateOptions contain uri category contentType user User is required Category ContentType and Uri are optional Example JavaScript function addTranslationArray var languageFrom en var languageTo fr var firstText OriginalText original1 TranslatedText translated1 Rating 1 var secondText OriginalText original2 TranslatedText translated2 Rating 2 var thirdText OriginalText original3 TranslatedText translated3 Rating 3 var arrayText firstText secondText thirdText var options User defaultUser var s document createElement script s src appId myAppId document getElementsByTagName head 0 appendChild s alert Translations have been submitted BreakSentences Method Microsoft Translator V2 Breaks a piece of text into sentences and returns an array containing the lengths in each sentence Syntax URI Parameters Parameter Description appId A string containing the Bing AppID text A string representing the text to split into sentences language A string representing the language code of input text Return Value An array of integers representing the lengths of the sentences The length of the array is the enumber of sentences and the values are the length of each sentence Example JavaScript function breakSentence window mycallback function response var result BreakSentences broke up the above sentence into result response length sentences result The lengths of the sentences are for var i 0 i response length i result response i if i response length 1 result result characters respectively alert result var text encodeURIComponent This is one sentence The method will count this as the second sentences Finally the third sentence var language en var s document createElement script s src document getElementsByTagName head 0 appendChild s Detect Method Microsoft Translator V2 Use the Detect Method to identify the language of a selected piece of text Syntax URI Parameters Parameter Description appId A string containing the Bing AppID text A string representing the text from an unknown language Example JavaScript var text encodeURIComponent The language of this text is going to be detected function detect window mycallback function response alert The detected language is response var s document createElement script s src document getElementsByTagName head 0 appendChild s DetectArray Method Microsoft Translator V2 Use the DetectArray Method to identify the language of an array of strings all at once Performs independent detection of each individual array element and returns a result for each element of the array Syntax URI Parameters Parameter Description appId A string containing the Bing AppID texts A string array representing the text from an unknown language Example JavaScript var texts This is English text Das ist deutsche Text Questo un testo italiano function detectArray window mycallback function response var array response var detectedLanguages for var i 0 i array length i detectedLanguages detectedLanguages array i n alert detectedLanguages var s document createElement script s src document getElementsByTagName head 0 appendChild s GetAppIdToken Method Microsoft Translator V2 Returns a tokenized AppID which can be used as the AppID parameter in any method except GetAppIdToken A tokenized AppID should be used when the appID must be kept secret Syntax URI Parameters Parameter Description appId A string containing the Bing AppId minRatingRead An int to define the minimum rating translations require to be returned The recommended minRatingRead is 5 as this will only include automatic translations and authority approved translations maxRatingWrite An int to define the maximum rating that a user can write with using this token The recommended maxRatingWrite is from 1 to 4 for anonymous users and from 6 to 10 for authoritative users whom you trust Translations with ratings of 5 or higher will replace automatic translations when calling Translate or TranslateArray with the same appId Translations with ratings lower then 5 will only be returned when calling GetTranslations or GetTranslationsArray expireSeconds An int that defines the duration in seconds from now that the token is valid The value can be between 1 and 86400 24 hours Return Value A string representing the tokenized identification for the calling application Example JavaScript function getAppIdToken window mycallback function response alert The tokenized AppID is response var s document createElement script s src document getElementsByTagName head 0 appendChild s GetLanguageNames Method Microsoft Translator V2 Retrieves friendly names for the languages passed in as the parameter languageCodes and localized using the passed locale language Syntax URI Parameters Parameter Description appId A string containing the Bing AppID locale A string representing a combination of an ISO 639 two letter lowercase culture code associated with a language and an ISO 3166 two letter uppercase subculture code to localize the language names or a ISO 639 lowercase culture code by itself languageCodes A string array representing the ISO 639 1 language codes to retrieve the friendly name for Return Value A string array containing the friendly language names of the passed languageCodes Example JavaScript var languageCodes de fr it function getLanguageNames window mycallback function response var array response var languageNames for var i 0 i array length i languageNames languageNames array i n alert languageNames var s document createElement script s src document getElementsByTagName head 0 appendChild s GetLanguagesForSpeak Method Microsoft Translator V2 Retrieves the languages available for speech synthesis Syntax URI Parameters Parameter Description appId A string containing the Bing AppID Return Value A string array containing the language codes supported for speech synthesis by the Translator Services Example JavaScript var languages function getLanguagesForSpeak window mycallback function response for var i 0 i response length i languages languages response i alert The available languages are response var s document createElement script s src document getElementsByTagName head 0 appendChild s GetLanguagesForTranslate Method Microsoft Translator V2 Obtain a list of language codes representing languages that are supported by the Translation Service Translate and TranslateArray can translate between any of these languages Syntax URI te Parameters Parameter Description appId A string containing the Bing AppID Return Value A string array containing the language codes supported by the Translator Services Example JavaScript var languages function getLanguagesForTranslate window mycallback function response for var i 0 i response length i languages languages response i alert The available languages are response var s document createElement script s src GetTranslations Method Microsoft Translator V2 Retrieves an array of translations for a given language pair from the store and the MT engine GetTranslations differs from Translate as it returns all available translations Syntax URI Parameters Parameter Description appId A string containing the Bing AppID text A string representing the text to translate from A string representing the language code of the translation text to A string representing the language code to translate the text into maxTranslations An int representing the maximum number of translations to return options A TranslateOptions object which contains the values listed below They are all optional and default to the most common settings Category A string containing the category domain of the translation Defaults to general ContentType A string containing the type of content Either text html or text plain Defaults to text plain Uri A string containing the content location of this translation User A string used to track the originator of the submission State User state to help correlate request and response The same contents will be returned in the response Return Value A GetTranslationsResponse containing the following values Translations An array of matches found stored in TranslationMatch see below objects The translations may include slight variants of the original text fuzzy matching The translations will be sorted 100 matches first fuzzy matches below From If the method did not specify a From language this will be the result of auto language detection Otherwise it will be the given From language State User state to help correlate request and response Contains the same value as given in the TranslateOptions parameter A TranslationMatch object consists of the following Error If an error has occurred for a specific input string the error code is stored Otherwise the field is empty MatchDegree The system matches input sentences against the store including inexact matches MatchDegree indicates how closely the input text matches the original text found in the store The value returned ranges from 0 to 100 where 0 is no similarity and 100 is an exact case sensitive match MatchedOriginalText Original text that was matched for this result Only returned if the matched original text was different than the input text Used to return the source text of a fuzzy match Not returned for Microsoft Translator results Rating Indicates the authority of the person making the quality decision Machine Translation results will have a rating of 5 Anonymously provided translations will generally have a rating of 1 to 4 whilst authoritatively provided translations will generally have a rating of 6 to 10 Count The number of times this translation with this rating has been selected The value will be 0 for the automatically translated response TranslatedText The translated text Example JavaScript var languageFrom en var languageTo es var text alternative translations var options State someUniqueStateId function getTranslations window mycallback function response var array response Translations var translations for var i 0 i array length i translations translations array i TranslatedText n alert translations var s document createElement script s src document getElementsByTagName head 0 appendChild s GetTranslationsArray Method Microsoft Translator V2 Use the GetTranslationsArray method to retrieve multiple translation candidates for multiple source texts Syntax URI Parameters Parameter Description appId A string containing the Bing AppID texts An array containing the texts for translation All strings should be of the same language from A string representing the language code of the translation text to A string representing the language code to translate the text into maxTranslations An int representing the maximum number of translations to return options A TranslateOptions object which contains the values listed below They all default to the most common settings You do not need to set any of the values Category A string containing the category domain of the translation Defaults to general ContentType A string containing the type of content Either text html or text plain Defaults to text plain Uri A string containing the content location of this translation User A string used to track the originator of the submission State User state to help correlate request and response The same contents will be returned in the response Return Value Returns a GetTranslationsResponse array Each GetTranslationsResponse has the following elements Translations An array of matches found stored in TranslationMatch see below objects The translations may include slight variants of the original text fuzzy matching The translations will be sorted 100 matches first fuzzy matches below From If the method did not specify a From language this will be the result of auto language detection Otherwise it will be the given From language State User state to help correlate request and response Contains the same value as given in the TranslateOptions parameter A TranslationMatch object consists of the following Error If an error has occurred for a specific input string the error code is stored Otherwise the field is empty MatchDegree The system matches input sentences against the store including inexact matches MatchDegree indicates how closely the input text matches the original text found in the store The value returned ranges from 0 to 100 where 0 is no similarity and 100 is an exact case sensitive match MatchedOriginalText Original text that was matched for this result Only returned if the matched original text was different than the input text Used to return the source text of a fuzzy match Not returned for Microsoft Translator results Rating Indicates the authority of the person making the quality decision Machine Translation results will have a rating of 5 End user submitted translations will generally have a rating of 1 to 4 whilst webmaster approved translations will generally have a rating of 6 to 10 Count The number of times this translation with this rating has been selected by the users The value will be 0 for the automatically translated response TranslatedText The translated text Example Javascript function getTranslationsArray window mycallback function response var array response var translations for var i 0 i array length i for var count 0 count array i Translations length count translations translations i 1 count 1 array i Translations count TranslatedText alert translations var languageFrom en var languageTo de var texts encodeURIComponent element1 encodeURIComponent element2 encodeURIComponent element3 var maxTranslations 5 var options State so