|
| 1 | +Azure Translator in Foundry Tools provides an API for translating text between over 90 supported languages. With Azure Translator you can: |
| 2 | + |
| 3 | +- Translate or transliterate text using the default translation model or a large language model (LLM). |
| 4 | +- Translate documents, synchronously or asynchronously, while maintaining document structure. |
| 5 | +- Use custom translation models to translate domain-specific terms. |
| 6 | + |
| 7 | +We'll focus on the *text translation* API in this module. You can find out more about the full range of Azure Translator capabilities in the [Azure Translator in Foundry Tools documentation](/azure/ai-services/translator?azure-portal=true). |
| 8 | + |
| 9 | +## Use Azure Translator in the Microsoft Foundry portal |
| 10 | + |
| 11 | +You can explore Azure Translator in the Microsoft Foundry portal, where there are playgrounds for text translation and document translation. |
| 12 | + |
| 13 | + |
| 14 | + |
| 15 | +The Foundry portal is a great way to experiment with Azure translator, comparing results from the default model with those from LLMs, and viewing sample code to use the translator from your own client applications. |
| 16 | + |
| 17 | +## Use Azure Translator in application code |
| 18 | + |
| 19 | +You can use the [REST API](/azure/ai-services/translator/text-translation/reference/rest-api-guide?azure-portal=true) to call Azure Translator functions, or you can write code in your preferred language by using one of the supported SDKs; which include: |
| 20 | + |
| 21 | +- [Azure Translator Text Translation Client for Python](https://pypi.org/project/azure-ai-translation-text/1.0.1/?azure-portal=true) |
| 22 | +- [Azure Translator Text Translation Client for Microsoft .NET](https://www.nuget.org/packages/Azure.AI.Translation.Text/1.0.0?azure-portal=true) |
| 23 | +- [Azure Translator Text Translation Client for Java](https://mvnrepository.com/artifact/com.azure/azure-ai-translation-text/1.0.0?azure-portal=true) |
| 24 | +- [Azure Translator Text Translation Client for JavaScript](https://www.npmjs.com/package/@azure-rest/ai-translation-text/v/1.0.0?azure-portal=true) |
| 25 | + |
| 26 | +### Connect to an Azure Translator resource |
| 27 | + |
| 28 | +Azure Translator APIs are served through REST *endpoints*, to which your client must make an authenticated connection. The endpoint can be: |
| 29 | + |
| 30 | +- The Azure Translator *global* endpoint: `api.cognitive.microsofttranslator.com` |
| 31 | +- Azure Translator *regional* endpoints: These endpoints include `api-nam.cognitive.microsofttranslator.com`, `api-apc.cognitive.microsofttranslator.com`, and `api-eur.cognitive.microsofttranslator.com` |
| 32 | +- Foundry resource endpoints: `{foundry-resource-name}.cognitiveservices.azure.com/` |
| 33 | + |
| 34 | +You can connect a client to a specific endpoint, or you can connect by specifying the region in which your resource is provisioned. For example, you could use either of the techniques shown in the following code sample to connect to Azure Translator using your Foundry API key for authentication: |
| 35 | + |
| 36 | +```python |
| 37 | +from azure.core.credentials import AzureKeyCredential |
| 38 | +from azure.ai.translation.text import * |
| 39 | + |
| 40 | +key_credential = AzureKeyCredential("FOUNDRY_KEY") |
| 41 | + |
| 42 | +# Connect to a Foundry resource endpoint |
| 43 | +client = TextTranslationClient(credential=key_credential, endpoint="FOUNDRY_ENDPOINT") |
| 44 | + |
| 45 | +# Or connect using a region |
| 46 | +client = TextTranslationClient(credential=key_credential, region="FOUNDRY_REGION") |
| 47 | +``` |
| 48 | + |
| 49 | +> [!TIP] |
| 50 | +> For more information about the **TextTranslationClient** constructor, see the [Azure Translator Python SDK documentation](/python/api/azure-ai-translation-text/azure.ai.translation.text.texttranslationclient?azure-portal=true#constructor). |
| 51 | +
|
| 52 | +### Determine available languages |
| 53 | + |
| 54 | +Azure Translator supports over 90 languages. In some cases, you may want to provide users with a list of available languages for translation; as shown in the following example code: |
| 55 | + |
| 56 | +```python |
| 57 | +languages = client.get_supported_languages(scope="translation") |
| 58 | +print("{} languages supported:".format(len(languages.translation))) |
| 59 | +for language in languages.translation.keys(): |
| 60 | + print(languages.translation[language].name + " (" + language + ")") |
| 61 | +``` |
| 62 | + |
| 63 | +The results include the *name* and *ISO code* for each language: |
| 64 | + |
| 65 | +``` |
| 66 | +137 languages supported: |
| 67 | +Afrikaans (af) |
| 68 | +Amharic (am) |
| 69 | +Arabic (ar) |
| 70 | +Assamese (as) |
| 71 | +Azerbaijani (az) |
| 72 | +Bashkir (ba) |
| 73 | +Belarusian (be) |
| 74 | +Bulgarian (bg) |
| 75 | +... |
| 76 | +``` |
| 77 | + |
| 78 | +> [!TIP] |
| 79 | +> For more information about the **get_supported_language** method, see the [Azure Translator Python SDK documentation](python/api/azure-ai-translation-text/azure.ai.translation.text.texttranslationclient?azure-portal=true#azure-ai-translation-text-texttranslationclient-get-supported-languages). |
| 80 | +
|
| 81 | +### Translate text |
| 82 | + |
| 83 | +To translate text from a *source* language to one or more *target* languages, use the **translate** method. |
| 84 | + |
| 85 | +- Source text is passed into the method as a list of **InputTextItem** objects, each containing a text string to be translated. |
| 86 | +- You can optionally specify a **from_language** parameter with the ISO code for the source language (for example, "en"); or you can omit this parameter to have Azure Translator automatically detect the source language. |
| 87 | +- Target languages as specified as a list of language codes in the **to_language** parameter - Azure Translator will return a translation for each valid language code. |
| 88 | + |
| 89 | +The following example translates two text inputs in different unspecified languages into French (*fr*) and English (*en*): |
| 90 | + |
| 91 | +```python |
| 92 | +input_text_elements = [InputTextItem(text="Hola"), InputTextItem(text="こんにちは")] |
| 93 | +translation_results = client.translate(body=input_text_elements, to_language=["fr", "en"]) |
| 94 | +idx = 0 |
| 95 | +for translation in translation_results: |
| 96 | + input_text = input_text_elements[idx].text |
| 97 | + idx += 1 |
| 98 | + sourceLanguage = translation.detected_language |
| 99 | + for translated_text in translation.translations: |
| 100 | + print(f"'{input_text}' was translated from {sourceLanguage.language} to {translated_text.to} as '{translated_text.text}'.") |
| 101 | +``` |
| 102 | + |
| 103 | +The output from this code shows the detected source languages as Spanish (*es*) and Japanese (*ja*): |
| 104 | + |
| 105 | +``` |
| 106 | +'Hola' was translated from es to fr as 'Bonjour'. |
| 107 | +'Hola' was translated from es to en as 'Hello'. |
| 108 | +'こんにちは' was translated from ja to fr as 'Bonjour'. |
| 109 | +'こんにちは' was translated from ja to en as 'Hello'. |
| 110 | +``` |
| 111 | + |
| 112 | +> [!TIP] |
| 113 | +> For more information about the **translate** method, see the [Azure Translator Python SDK documentation](/python/api/azure-ai-translation-text/azure.ai.translation.text.texttranslationclient?azure-portal=true#azure-ai-translation-text-texttranslationclient-translate). |
| 114 | +
|
| 115 | +### Transliterate text |
| 116 | + |
| 117 | +The Japanese text in the previous example is written using Hiragana script, so rather than translate it to a different language, you may want to transliterate it to a different script - for example to render the Japanese words in Latin script (as used by English language text). |
| 118 | + |
| 119 | +To accomplish this, we can submit the Japanese text to the **transliterate** method with a **from_script** parameter of **Jpan** and a **to_script** parameter of **Latn**, like this: |
| 120 | + |
| 121 | +```python |
| 122 | +source_text = "こんにちは" |
| 123 | +input_text_elements = [InputTextItem(text=source_text)] |
| 124 | +transliteration_results = client.transliterate(body=input_text_elements, language="ja", |
| 125 | + from_script="Jpan", to_script="Latn") |
| 126 | +for transliteration in transliteration_results: |
| 127 | + sourceScript = transliteration.script |
| 128 | + targetScript = transliteration.text |
| 129 | + print(f"'{source_text}' was transliterated into {sourceScript} as {targetScript}.") |
| 130 | +``` |
| 131 | + |
| 132 | +This code example produces the following result: |
| 133 | + |
| 134 | +``` |
| 135 | +'こんにちは' was transliterated into Latn as Kon'nichiwa. |
| 136 | +``` |
| 137 | + |
| 138 | +> [!TIP] |
| 139 | +> For more information about the **transliterate** method, see the [Azure Translator Python SDK documentation](/python/api/azure-ai-translation-text/azure.ai.translation.text.texttranslationclient?azure-portal=true#azure-ai-translation-text-texttranslationclient-transliterate). |
0 commit comments