Overview
The Azure Cognitive Services Translator connector for Bizagi is available for download at Bizagi Connectors Xchange.
Through this connector, you will be able to connect your Bizagi processes to your Azure Cognitive Services Translator account and services. That is, having automatic translations in more than 90 different languages.
For more information about this connector's capabilities, visit Bizagi Connectors Xchange.
|
This Connector was developed according to the contents of the API and the information about it provided by Azure Cognitive Services Translator. Bizagi and its subsidiaries will not provide any kind of guarantee over the content or error caused by calling the API services. Bizagi and its subsidiaries are not responsible for any loss, cost or damage consequence of the calls to Azure Cognitive Services Translator 's API. |
Before you start
To test and use this connector, you will need:
1.Bizagi Studio previously installed.
2.This connector previously installed, via the Connectors Xchange as described at https://help.bizagi.com/platform/en/index.html?Connectors_Xchange.htm, or through a manual installation as described at https://help.bizagi.com/platform/en/index.html?connectors_setup.htm.
3.A Translator resource created in your Azure subscription. To know how to create a Translator resource in your Azure subscription, click here.
Configuring the connector
To configure the connector, follow the steps presented at the Configuration chapter in https://help.bizagi.com/platform/en/index.html?connectors_setup.htm.
For this configuration, consider the following parameters:
Connector parameters
•REGION: Region configured in the Azure Portal.
•API_VERSION: Currently the connector works with the API version 3.0.
Authentication parameters
•Authentication method: Custom
•SUBSCRIPTION_KEY: The key obtained after creating the Translator resource in the Azure Portal.
Using the connector
This connector features a set of methods which lets you use Azure Cognitive Services Translator's API services to take advantage of their capabilities.
To learn overall how/where to configure the use of a connector, refer to https://help.bizagi.com/platform/en/index.html?Connectors_Studio.htm.
When using the connector, keep in mind they may need input or output configurations. The following images show examples of how to map the inputs or outputs of a method.
Available actions
Translate
This action translates a text from one language to another.
To configure its inputs, take into account the following descriptions:
•textList (Collection): collection that contains the following parameters:
otext (String): texts that you want to translate.
•to (Required): specifies the language to which the texts are going to be translated. This language must be specified through a language code and must be one of the api's supported languages. This parameter should be a String in your Bizagi model.
•toScript (String): specifies the script of the translated text.
•from (String): specifies the language of the input text. If the input language is not specified, an automatic language detection is applied to the text to identify it.
•allowFallback (Boolean): specifies that the service is allowed to fallback to a general system when a custom system does not exist.
•includeAlignment (Boolean): specifies if an alignment projection should be included from the input text to the translated text.
•includeSentenceLength (Boolean): specifies whether to include sentence boundaries for the input text and the translated text.
•profanityAction (String): specifies how to treat profanities within translations. Possible values are NoAction (default value), Marked or Deleted. To know more about how to handle profanities, click here.
•textType (String): defines if the input text is plain text or HTTML text. The HTML text must be a complete element and well formatted. Possible values for this parameter are plain (default value) or html.
•category (String): a string that specifies the translation category (domain). This parameter is used to get translations from a customized system built with Custom Translator. Add the Category ID from your Custom Translator project details to this parameter to use your deployed customized system. Default value is: general.
•profanityMarker (String): specifies how to mark profanities within translations. Possible values are asterisk (default value) or tag. To know more about how to handle profanities, click here.
•suggestedFrom (String): specifies a fallback language for when the input text can't be identified. The automatic language detectiton is applied when the from parameter is not defined. If the language detection fails, the suggestedFrom language is used.
•fromScript (String): specifies the script of the input text.
|
The collection can have at most 100 elements. The entire text included in the request cannot exceed 10.000 characters (including spaces). |
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•detectedLanguage (String): object that describes the detected language. The detectedLanguage property is included in the result object when the language auto-detection is requested. This object includes the following properties:
olanguage (String): string that represents the code of the detected language.
oscore (Number): float value that indicates the result confidence. This score is between 0 and 1.
•translations (String): array of the translation results. The size of the array matches the number of target languages defined in the to input. Each element of the array includes the following properties:
oto (String): string that represents the code of the detected language.
otext (String): string with the text translated.
otransliteration (String): object giving the translated text in the script defined in the toScript input. The transliteration property is not included in the result object if there is no transliteration. This object includes the following properties:
▪script (String): string that specifies the target script.
▪text (String): string with the translated text in the target script.
oalignment (String): object with a single property (proj), which maps the input text to the translated text. This object is only included in the result object when the includeAlignment property is true in the input.
osentLen (List Object): object that returns the sentence limits in the input and output texts. This object is only included in the result object when the includeSentenceLength property is true in the input and includes the following properties:
▪srcSentLen (List Number): an array with the lengths of the sentences in the input text. The length of the array depends on the number of sentences in the input text.
▪transSentLen (List Number): an array with the lengths of the sentences in the translated text. The length of the array depends on the number of sentences in the translated text.
•sourceText (String): object with a single property (String), which gives the input text inthe default script of the source language.
For more information about this method's use, refer to Azure Cognitive Services Translator 's official documentation at https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-translate.
Transliterate
This action converts text in one language from one script to another script.
To configure its inputs, take into account the following descriptions:
•textList (Collection): collection that contains the following parameters:
otext (String): texts that you want to translate.
oscript (String): string that specifies the script to be used in the output.
•language (Required): specifies the language of the input text. The possible languages are listed in the transliteration scope, obtained by querying the service for its [supported languages](./v3-0-languages.md). This parameter should be a string in your Bizagi model.
•toScript (Required): specifies the output script. Look up [supported languages](./v3-0-languages.md) using the transliteration scope, to find output scripts available for the selected combination of input language and input script. This parameter should be a String in your Bizagi model.
•fromScript (Required): specifies the script used by the input text. Look up [supported languages](./v3-0-languages.md) using the transliteration scope, to find output scripts available for the selected combination of input language and input script. This parameter should be a String in your Bizagi model.
|
The collection can have at most 10 elements. The text value of an array element cannot exceed 1.000 characters (including spaces). The entire text included in the request cannot exceed 5.000 characters (including spaces). |
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•output: array of the transliteration results. The size of the array matches the size of the input array. Each element of the array includes the following properties:
otext (String): translated texts.
oscript (String): string that specifies the script used in the output.
For more information about this method's use, refer to Azure Cognitive Services Translator 's official documentation at https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-transliterate.
Detect
This action identifies the language of a text.
To configure its inputs, take into account the following descriptions:
•textList (Collection): collection that contains the following parameters:
otext (String): texts that you want to translate.
|
The collection can have at most 100 elements. The entire text included in the request cannot exceed 50.000 characters (including spaces). |
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
language (String): string that represents the code of the detected language.
•score (Number): float value that indicates the result confidence. This score is between 0 and 1.
•isTranslationSupported (Boolean): boolean value that indicates if the detected language is supported for text translation.
•isTransliterationSupported (Boolean): boolean value that indicates if the detected language is supported for text transliteration.
•alternatives (Collection): array of possible languages. Each element of the array is an object with the same properties listed above:
olanguage (String): string that represents the code of the detected language.
oscore (Number): float value that indicates the result confidence. This score is between 0 and 1.
oisTranslationSupported (Boolean): boolean value that indicates if the detected language is supported for text translation.
oisTransliterationSupported (Boolean): boolean value that indicates if the detected language is supported for text transliteration.
For more information about this method's use, refer to Azure Cognitive Services Translator 's official documentation at https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-detect.
Break Sentence
This action Identifies the positioning of sentence boundaries in a piece of text.
To configure its inputs, take into account the following descriptions:
•textList (Collection): collection that contains the following parameters:
otext (String): text that you want to translate.
•language (String): specifies language code of the input text. If no language code is specified, the service uses automatic language detection.
•script (String): string that specifies the script of the input text. If no script is specified, the default script of the language is assumed.
|
The collection can have at most 100 elements. The text value of an array element cannot exceed 50.000 characters (including spaces). The entire text included in the request cannot exceed 50.000 characters (including spaces). If the language parameter is specified, all the elements of the array must be in the same language. |
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
•sentLen (List Object): an array with the lengths of the sentences in the input text. The length of the array depends on the number of sentences in the input text.
•detectedLanguage (Object): object with the detected language of the sentences. This object is only included in the result object when the language detection is requested. The object includes the following properties:
olanguage (String): string that represents the code of the detected language.
oscore (Number): float value that indicates the result confidence. This score is between 0 and 1.
For more information about this method's use, refer to Azure Cognitive Services Translator 's official documentation at https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-break-sentence.
Dictionary Lookup
This action provides an alternative translation for a word or for a small sentence.
To configure its inputs, take into account the following descriptions:
•textList (Collection): collection that contains the following parameters:
otext (String): text that you want to lookup.
•from (String - Required): specifies the language of the input text. The language must be included in the dictionary scope of the api's supported languages. This parameter should be a String in your Bizagi model.
•to (String - Required): specifies the language of the output text. The language must be included in the dictionary scope of the api's supported languages. This parameter should be a String in your Bizagi model.
|
The collection can have at most 10 elements. The text value of an array element cannot exceed 100 characters (including spaces). |
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
The outputs of this action are the following:
•normalizedSource (String): string that contains the normalized form of the source text. For example, if the request is AUTOMATION, the normalized text is automation. This text becomes the input for a dictionary example.
•displaySource (String): string that contains the accurate text for end-user display. For example, if the request is JHON, the display text is Jhon, as it is the usual spelling for the proper name.
•translations (Collection): list of translations for the source text. Each element of the list includes the following properties:
onormalizedTarget (String): string that contains the normalized form of the text in the translated language.
odisplayTarget (String): string that contains the accurate text for end-user display in the translated language.
oposTag (String): string that associates the text with a part-of-speech tag. Some of the tags may be:
▪ADJ -> Adjectives
▪ADV -> Adverbs
▪CONJ -> Conjunctions
▪NOUN -> Nouns
▪PRON -> Pronouns
oconfidence: float value that indicates the result confidence. This score is between 0 and 1.
oprefixWord (String): string that gives the word to display as a prefix of the translation. For example, this is the gender determiner for nouns. If there is no prefix, this object will be empty.
obackTranslations (Collection): list of "back translations" of the target. For example, source words that the target can translate to. The list is guaranteed to contain the source word that was requested (e.g., if the source word being looked up is "fly", then it is guaranteed that "fly" will be in the backTranslations list). Each element of the list is an object described by the following properties:
▪normalizedText (String): string that contains the normalized form of the text that is a back-translation of the source text.
▪displayText (String): string that contains the accurate text for end-user display of the text that is a back-translation of the source text.
▪numExamples (Integer): integer that indicates the number of available examples for the translation pair. Bear in mind that this parameter only includes the name. The actual translations are retrieved through the dictionary examples action.
▪frequencyCount (Integer): integer indicating the frequency of the translation pair in the data.
For more information about this method's use, refer to Azure Cognitive Services Translator 's official documentation at https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-dictionary-lookup.
Dictionary Examples
This action provides examples that show how terms in the dictionary are used in context.
To configure its inputs, take into account the following descriptions:
• textList (Collection): collection that contains the following parameters:
o text (String): text that you want to lookup. This text should be the value of a normalizedText field from the back-translations of a previous dictionary lookup request.
o Translation (String): string that specifies the translated text previously obtained through a dictionary lookup operation. This text should be the value of a normalizedText field from the translations list of a previous dictionary lookup response.
•from (String - Required): specifies the language of the input text. The language must be included in the dictionary scope of the api's supported languages. This parameter should be a String in your Bizagi model.
•to (String - Required): specifies the language of the output text. The language must be included in the dictionary scope of the api's supported languages. This parameter should be a String in your Bizagi model.
|
The collection can have at most 10 elements. The text value of an array element cannot exceed 100 characters (including spaces). |
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
The outputs of this action are the following:
•normalizedSource (String): string that contains the normalized form of the source text. For example, if the request is AUTOMATION, the normalized text is automation. This text becomes the input for a dictionary example.
•normalizedText (String): string that contains the normalized form of the target text.
•examples: list of examples for the source term and the target term. Each element of the list is an object that includes the following properties:
osourceTerm (String): string equal to the actual term looked up. By adding the sourcePrefix and the sourceSuffix to this string, you obtain a complete example.
osourcePrefix (String): string to concatenate before the value of sourceTerm to form a complete example. This value may be an empty string.
osourceSuffix (String): string to concatenate after the value of sourceTerm to form a complete example. This value may be an empty string.
otargetTerm (String): string similar to the sourceTerm, but for the target. By adding the targetPrefix and the targetSuffix to this string, you obtain a complete example.
otargetPrefix (String): string to concatenate before the value of targetTerm to form a complete example. This value may be an empty string.
otargetSuffix (String): string to concatenate after the value of targetTerm to form a complete example. This value may be an empty string.
For more information about this method's use, refer to Azure Cognitive Services Translator 's official documentation at https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-dictionary-examples.
Languages
This action gets the set of languages currently supported by other operations of the Translator.
You don't need to provide any input for this action.
To configure the outputs of this action, you can map the output object to the corresponding entity in Bizagi and make sure you map the attributes of the entity appropriately.
The outputs of this action are the following:
•languages (Collection): collection with the objects that represent the language information. Each language has the following properties:
ocode (String): language BCP 47 code. The code identifies a language for which the text can be translated to, or translated from.
oname (String): display name of the language in the locale requested via Accept-Language header.
onativeName (String): display name of the language in the locale native for this language.
odir (String): directionality, which is rtl for right-to-left languages, or ltr for left-to-right languages.
For more information about this method's use, refer to Azure Cognitive Services Translator 's official documentation at https://docs.microsoft.com/en-us/azure/cognitive-services/translator/reference/v3-0-languages.
Last Updated 10/27/2022 11:25:21 AM