Azure.AI.Translation.Text 1.0.0

Azure Text Translation client library for .NET

Text translation is a cloud-based REST API feature of the Translator service that uses neural machine translation technology to enable quick and accurate source-to-target text translation in real time across all supported languages.

Use the Text Translation client library for .NET to:

• Return a list of languages supported by Translate, Transliterate, and Dictionary operations.

• Render single source-language text to multiple target-language texts with a single request.

• Convert text of a source language in letters of a different script.

• Return equivalent words for the source term in the target language.

• Return grammatical structure and context examples for the source term and target term pair.

Source code | API reference documentation | Product documentation

Getting started

Install the package

Install the Azure Text Translation client library for .NET with NuGet:

dotnet add package Azure.AI.Translation.Text --prerelease

This table shows the relationship between SDK versions and supported API versions of the service:

Prerequisites

• An Azure subscription.
• An existing Translator service or Cognitive Services resource. You can create Translator resource following Create a Translator resource.

Authenticate the client

Interaction with the service using the client library begins with creating an instance of the TextTranslationClient class. You will need an API key or TokenCredential to instantiate a client object. For more information regarding authenticating with Cognitive Services, see Authenticate requests to Translator Service.

Get an API key

You can get the endpoint, API key and Region from the Cognitive Services resource or Translator service resource information in the Azure Portal.

Alternatively, use the Azure CLI snippet below to get the API key from the Translator service resource.

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Create a TextTranslationClient using an API key and Region credential

Once you have the value for the API key and Region, create an AzureKeyCredential. This will allow you to update the API key without creating a new client.

With the value of the endpoint, AzureKeyCredential and a Region, you can create the TextTranslationClient:

string endpoint = "<Text Translator Resource Endpoint>";
string apiKey = "<Text Translator Resource API Key>";
string region = "<Text Translator Azure Region>";
TextTranslationClient client = new TextTranslationClient(new AzureKeyCredential(apiKey), new Uri(endpoint), region);

Create TextTranslationClient with Microsoft Entra ID

Client API key authentication is used in most of the examples, but you can also authenticate with Microsoft Entra ID using the Azure Identity library. To use the DefaultAzureCredential provider shown below, install the Azure.Identity package:

dotnet add package Azure.Identity

Create a custom subdomain for your resource in order to use this type of authentication. Use this value for the endpoint variable for Text Translator Custom Endpoint.

You will also need to register a new Microsoft Entra application and grant access to your Translator resource by assigning the "Cognitive Services User" role to your service principal. Additional information about Microsoft Entra authentication is available here.

Set the values of the client ID, tenant ID, and client secret of the Microsoft Entra application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. The DefaultAzureCredential constructor uses these variables to create your credentials.

string endpoint = "<Text Translator Custom Endpoint>";
DefaultAzureCredential credential = new DefaultAzureCredential();
TextTranslationClient client = new TextTranslationClient(credential, new Uri(endpoint));

Key concepts

TextTranslationClient

A TextTranslationClient is the primary interface for developers using the Text Translation client library. It provides both synchronous and asynchronous operations to access a specific use of text translator, such as get supported languages detection or text translation.

Input

A text element (string), is a single unit of input to be processed by the translation models in the Translator service. Operations on TextTranslationClient may take a single text element or a collection of text elements. For text element length limits, maximum requests size, and supported text encoding see here.

Return value

Return values, such as Response<IReadOnlyList<TranslatedTextItem>>, is the result of a Text Translation operation, It contains array with one result for each string in the input array. An operation's return value also may optionally include information about the input text element (for example detected language).

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

The following section provides several code snippets using the client created above, and covers the main features present in this client library. Although the snippets below make use of synchronous service calls, keep in mind that the Azure.AI.Translation.Text package supports both synchronous and asynchronous APIs.

Get Supported Languages

Gets the set of languages currently supported by other operations of the Translator.

try
{
    Response<GetSupportedLanguagesResult> response = client.GetSupportedLanguages(cancellationToken: CancellationToken.None);
    GetSupportedLanguagesResult languages = response.Value;

    Console.WriteLine($"Number of supported languages for translate operations: {languages.Translation.Count}.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

For samples on using the languages endpoint refer to more samples here.

Please refer to the service documentation for a conceptual discussion of languages.

Translate

The simplest use of the Translate method is to invoke it with a single target language and one input string.

try
{
    string targetLanguage = "cs";
    string inputText = "This is a test.";

    Response<IReadOnlyList<TranslatedTextItem>> response = client.Translate(targetLanguage, inputText);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;
    TranslatedTextItem translation = translations.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {translation?.DetectedLanguage?.Language} with score: {translation?.DetectedLanguage?.Confidence}.");
    Console.WriteLine($"Text was translated to: '{translation?.Translations?.FirstOrDefault().TargetLanguage}' and the result is: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

A convenience overload of Translate is provided using a TextTranslationTranslateOptions parameter. This sample demonstrates rendering a single source-language to multiple target languages with a single request using the options overload.

try
{
    TextTranslationTranslateOptions options = new TextTranslationTranslateOptions(
        targetLanguages: new[] { "cs", "es", "de" },
        content: new[] { "This is a test." }
    );

    Response<IReadOnlyList<TranslatedTextItem>> response = client.Translate(options);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;

    foreach (TranslatedTextItem translation in translations)
    {
        Console.WriteLine($"Detected languages of the input text: {translation?.DetectedLanguage?.Language} with score: {translation?.DetectedLanguage?.Confidence}.");

        Console.WriteLine($"Text was translated to: '{translation?.Translations?.FirstOrDefault().TargetLanguage}' and the result is: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
    }
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

This sample demonstrates Translation and Transliteration in a single call using the TextTranslationTranslateOptions parameter. Required parameters are passed to the constructor, optional parameters are set using an object initializer.

try
{
    TextTranslationTranslateOptions options = new TextTranslationTranslateOptions(
        targetLanguage: "zh-Hans",
        content: "hudha akhtabar.")
    {
        FromScript = "Latn",
        SourceLanguage = "ar",
        ToScript = "Latn"
    };

    Response<IReadOnlyList<TranslatedTextItem>> response = client.Translate(options);
    IReadOnlyList<TranslatedTextItem> translations = response.Value;
    TranslatedTextItem translation = translations.FirstOrDefault();

    Console.WriteLine($"Source Text: {translation.SourceText.Text}");
    Console.WriteLine($"Translation: '{translation?.Translations?.FirstOrDefault()?.Text}'.");
    Console.WriteLine($"Transliterated text ({translation?.Translations?.FirstOrDefault()?.Transliteration?.Script}): {translation?.Translations?.FirstOrDefault()?.Transliteration?.Text}");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

For samples on using the translate endpoint refer to more samples here.

Please refer to the service documentation for a conceptual discussion of translate.

Transliterate

Converts characters or letters of a source language to the corresponding characters or letters of a target language.

try
{
    string language = "zh-Hans";
    string fromScript = "Hans";
    string toScript = "Latn";

    string inputText = "这是个测试。";

    Response<IReadOnlyList<TransliteratedText>> response = client.Transliterate(language, fromScript, toScript, inputText);
    IReadOnlyList<TransliteratedText> transliterations = response.Value;
    TransliteratedText transliteration = transliterations.FirstOrDefault();

    Console.WriteLine($"Input text was transliterated to '{transliteration?.Script}' script. Transliterated text: '{transliteration?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

A convenience overload of Transliterate is provided using a single TextTranslationTransliterateOptions parameter. A modified version of the preceding sample is provided here demonstrating its use.

try
{
    TextTranslationTransliterateOptions options = new TextTranslationTransliterateOptions(
        language: "zh-Hans",
        fromScript: "Hans",
        toScript: "Latn",
        content: "这是个测试。"
    );

    Response<IReadOnlyList<TransliteratedText>> response = client.Transliterate(options);
    IReadOnlyList<TransliteratedText> transliterations = response.Value;
    TransliteratedText transliteration = transliterations.FirstOrDefault();

    Console.WriteLine($"Input text was transliterated to '{transliteration?.Script}' script. Transliterated text: '{transliteration?.Text}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

For samples on using the transliterate endpoint refer to more samples here.

Please refer to the service documentation for a conceptual discussion of transliterate.

Break Sentence

Identifies the positioning of sentence boundaries in a piece of text.

try
{
    string inputText = "How are you? I am fine. What did you do today?";

    Response<IReadOnlyList<BreakSentenceItem>> response = client.FindSentenceBoundaries(inputText);
    IReadOnlyList<BreakSentenceItem> brokenSentences = response.Value;
    BreakSentenceItem brokenSentence = brokenSentences.FirstOrDefault();

    Console.WriteLine($"Detected languages of the input text: {brokenSentence?.DetectedLanguage?.Language} with score: {brokenSentence?.DetectedLanguage?.Confidence}.");
    Console.WriteLine($"The detected sentence boundaries: '{string.Join(",", brokenSentence?.SentencesLengths)}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

For samples on using the break sentece endpoint refer to more samples here.

Please refer to the service documentation for a conceptual discussion of break sentence.

Dictionary Lookup

Returns equivalent words for the source term in the target language.

try
{
    string sourceLanguage = "en";
    string targetLanguage = "es";
    string inputText = "fly";

    Response<IReadOnlyList<DictionaryLookupItem>> response = client.LookupDictionaryEntries(sourceLanguage, targetLanguage, inputText);
    IReadOnlyList<DictionaryLookupItem> dictionaryEntries = response.Value;
    DictionaryLookupItem dictionaryEntry = dictionaryEntries.FirstOrDefault();

    Console.WriteLine($"For the given input {dictionaryEntry?.Translations?.Count} entries were found in the dictionary.");
    Console.WriteLine($"First entry: '{dictionaryEntry?.Translations?.FirstOrDefault()?.DisplayTarget}', confidence: {dictionaryEntry?.Translations?.FirstOrDefault()?.Confidence}.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

For samples on using the dictionary lookup endpoint refer to more samples here.

Please refer to the service documentation for a conceptual discussion of dictionary lookup.

Dictionary Examples

Returns grammatical structure and context examples for the source term and target term pair.

try
{
    string sourceLanguage = "en";
    string targetLanguage = "es";
    IEnumerable<InputTextWithTranslation> inputTextElements = new[]
    {
        new InputTextWithTranslation("fly", "volar")
    };

    Response<IReadOnlyList<DictionaryExampleItem>> response = client.LookupDictionaryExamples(sourceLanguage, targetLanguage, inputTextElements);
    IReadOnlyList<DictionaryExampleItem> dictionaryEntries = response.Value;
    DictionaryExampleItem dictionaryEntry = dictionaryEntries.FirstOrDefault();

    Console.WriteLine($"For the given input {dictionaryEntry?.Examples?.Count} examples were found in the dictionary.");
    DictionaryExample firstExample = dictionaryEntry?.Examples?.FirstOrDefault();
    Console.WriteLine($"Example: '{string.Concat(firstExample.TargetPrefix, firstExample.TargetTerm, firstExample.TargetSuffix)}'.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

For samples on using the dictionary examples endpoint refer to more samples here.

Please refer to the service documentation for a conceptual discussion of dictionary examples.

Troubleshooting

When you interact with the Translator Service using the Text Translation client library, errors returned by the Translator service correspond to the same HTTP status codes returned for REST API requests.

For example, if you submit a translation request without a target translate language, a 400 error is returned, indicating "Bad Request".

try
{
    var translation = client.Translate(Array.Empty<string>(), new[] { "This is a Test" });
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

You will notice that additional information is logged, like the client request ID of the operation.

Message:
    Azure.RequestFailedException: Service request failed.
    Status: 400 (Bad Request)

Content:
    {"error":{"code":400036,"message":"The target language is not valid."}}

Headers:
    X-RequestId: REDACTED
    Access-Control-Expose-Headers: REDACTED
    X-Content-Type-Options: REDACTED
    Strict-Transport-Security: REDACTED
    Date: Mon, 27 Feb 2023 23:31:37 GMT
    Content-Type: text/plain; charset=utf-8
    Content-Length: 71

Setting up console logging

The simplest way to see the logs is to enable the console logging. To create an Azure SDK log listener that outputs messages to console use AzureEventSourceListener.CreateConsoleLogger method.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

To learn more about other logging mechanisms see here.

Next steps

Samples showing how to use this client library are available in this GitHub repository. Samples are provided for each main functional area, and for each area, samples are provided in both sync and async mode.

• Create TextTranslationClient
• Languages
• Translate
• Transliterate
• Break Sentence
• Dictionary Lookup
• Dictionary Examples

Contributing

See the CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.