Skip to content

Commit 23664d2

Browse files
a-noyassa-noyass
authored
Document translation samples and readme (Azure#19676)
1 parent 22065f4 commit 23664d2

18 files changed

+1596
-2
lines changed

‎sdk/documenttranslation/Azure.AI.DocumentTranslation/README.md‎

Lines changed: 531 additions & 1 deletion
Large diffs are not rendered by default.

‎sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
page_type: sample
3+
languages:
4+
- csharp
5+
products:
6+
- azure
7+
- azure-cognitive-services
8+
- azure-document-translation
9+
name: Azure DocumentTranslation samples for .NET
10+
description: Samples for the Azure.AI.DocumentTranslation client library
11+
---
12+
13+
# Azure Document Translation client SDK Samples
14+
Azure Cognitive Services Document Translation is a cloud service that translates documents to and from 90 languages and dialects while preserving document structure and data format. Use the client library for Document Translation to:
15+
16+
* Translate numerous, large files from an Azure Blob Storage container to a target container in your language of choice.
17+
* Check the translation status and progress of each document in the translation operation.
18+
* Apply a custom translation model or glossaries to tailor translation to your specific case.
19+
20+
## Common scenarios samples
21+
- [Start Translation](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample1_StartTranslation.md)
22+
- [Poll Documents Status](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample2_PollIndividualDocuments.md)
23+
- [Operations History](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample3_OperationsHistory.md)
24+
25+
## Advanced samples
26+
- [Multiple Configurations](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample4_MultipleConfigurations.md)
27+
28+
[README]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/textanalytics/Azure.AI.TextAnalytics/README.md

‎sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample1_StartTranslation.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Translating Documents
2+
This sample demonstrates how to translate one or more documents in a blob container. To get started you will need a Translator endpoint and credentials. See [README][README] for links and instructions.
3+
4+
## Creating a `DocumentTranslationClient`
5+
6+
To create a new `DocumentTranslationClient` to run a translation operation for documents, you need a Translator endpoint and credentials. In the sample below, you'll use a Translator API key credential by creating an `AzureKeyCredential` object, that if needed, will allow you to update the API key without creating a new client.
7+
8+
You can set `endpoint` and `apiKey` based on an environment variable, a configuration setting, or any way that works for your application.
9+
10+
```C# Snippet:CreateDocumentTranslationClient
11+
string endpoint = "<endpoint>";
12+
string apiKey = "<apiKey>";
13+
var client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));
14+
```
15+
16+
## Translating a single document or documents in a single container
17+
18+
To Start a translation operation for a single document or documents in a single blob container, call `StartTranslationAsync`. The result is a Long Running operation of type `DocumentTranslationOperation` which polls for the status of the translation operation from the API.
19+
20+
To call `StartTranslationAsync` you need to initialize an object of type `TranslationConfiguration` which contains the information needed to translate the documents.
21+
The `sourceUri` is a SAS URI with read access for the document to be translated or read and list access for the blob container holding the documents to be translated.
22+
The `targetUri` is a SAS URI with write access for the blob container to which the translated documents will be written.
23+
24+
More on generating SAS Tokens [here](https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/get-started-with-document-translation?tabs=csharp#create-sas-access-tokens-for-document-translation)
25+
26+
```C# Snippet:StartTranslationAsync
27+
Uri sourceUri = <source SAS URI>;
28+
Uri targetUri = <target SAS URI>;
29+
30+
var input = new TranslationConfiguration(sourceUri, targetUri, "es");
31+
32+
DocumentTranslationOperation operation = await client.StartTranslationAsync(input);
33+
34+
Response<AsyncPageable<DocumentStatusDetail>> operationResult = await operation.WaitForCompletionAsync();
35+
36+
Console.WriteLine($" Status: {operation.Status}");
37+
Console.WriteLine($" Created on: {operation.CreatedOn}");
38+
Console.WriteLine($" Last modified: {operation.LastModified}");
39+
Console.WriteLine($" Total documents: {operation.DocumentsTotal}");
40+
Console.WriteLine($" Succeeded: {operation.DocumentsSucceeded}");
41+
Console.WriteLine($" Failed: {operation.DocumentsFailed}");
42+
Console.WriteLine($" In Progress: {operation.DocumentsInProgress}");
43+
Console.WriteLine($" Not started: {operation.DocumentsNotStarted}");
44+
45+
await foreach (DocumentStatusDetail document in operationResult.Value)
46+
{
47+
Console.WriteLine($"Document with Id: {document.DocumentId}");
48+
Console.WriteLine($" Status:{document.Status}");
49+
if (document.Status == TranslationStatus.Succeeded)
50+
{
51+
Console.WriteLine($" Location: {document.LocationUri}");
52+
Console.WriteLine($" Translated to language: {document.TranslateTo}.");
53+
}
54+
else
55+
{
56+
Console.WriteLine($" Error Code: {document.Error.ErrorCode}");
57+
Console.WriteLine($" Message: {document.Error.Message}");
58+
}
59+
}
60+
```
61+
62+
To see the full example source files, see:
63+
64+
* [Synchronously StartTranslation ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_StartTranslation.cs)
65+
* [Asynchronously StartTranslation ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_StartTranslationAsync.cs)
66+
67+
[README]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/README.md

‎sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample2_PollIndividualDocuments.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Polling Documents Status
2+
This sample demonstrates how to poll the status of individual document in a translation operation. To get started you will need a Translator endpoint and credentials. See [README][README] for links and instructions.
3+
4+
## Creating a `DocumentTranslationClient`
5+
6+
To create a new `DocumentTranslationClient` to run a translation operation for documents, you need a Translator endpoint and credentials. In the sample below, you'll use a Translator API key credential by creating an `AzureKeyCredential` object, that if needed, will allow you to update the API key without creating a new client.
7+
8+
You can set `endpoint` and `apiKey` based on an environment variable, a configuration setting, or any way that works for your application.
9+
10+
```C# Snippet:CreateDocumentTranslationClient
11+
string endpoint = "<endpoint>";
12+
string apiKey = "<apiKey>";
13+
var client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));
14+
```
15+
16+
## Polling the status of documents in an operation
17+
18+
To poll the status of documents in an operation you use the `DocumentTranslationOperation` class which contains two functions `GetAllDocumentsStatusAsync` which returns the status of all documents in the operation and `GetDocumentStatusAsync` which returns the status of a specific document given its ID.
19+
20+
```C# Snippet:PollIndividualDocumentsAsync
21+
Uri sourceUri = <source SAS URI>;
22+
Uri targetUri = <target SAS URI>;
23+
24+
var input = new TranslationConfiguration(sourceUri, targetUri, "es");
25+
26+
DocumentTranslationOperation operation = await client.StartTranslationAsync(input);
27+
28+
TimeSpan pollingInterval = new TimeSpan(1000);
29+
30+
AsyncPageable<DocumentStatusDetail> documents = operation.GetAllDocumentsStatusAsync();
31+
await foreach (DocumentStatusDetail document in documents)
32+
{
33+
Console.WriteLine($"Polling Status for document{document.LocationUri}");
34+
35+
Response<DocumentStatusDetail> status = await operation.GetDocumentStatusAsync(document.DocumentId);
36+
37+
while (!status.Value.HasCompleted)
38+
{
39+
await Task.Delay(pollingInterval);
40+
status = await operation.GetDocumentStatusAsync(document.DocumentId);
41+
}
42+
43+
if (status.Value.Status == TranslationStatus.Succeeded)
44+
{
45+
Console.WriteLine($" Location: {document.LocationUri}");
46+
Console.WriteLine($" Translated to language: {document.TranslateTo}.");
47+
}
48+
else
49+
{
50+
Console.WriteLine($" Error Code: {document.Error.ErrorCode}");
51+
Console.WriteLine($" Message: {document.Error.Message}");
52+
}
53+
}
54+
```
55+
56+
To see the full example source files, see:
57+
58+
* [Synchronously PollIndividualDocuments ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_PollIndividualDocuments.cs)
59+
* [Asynchronously PollIndividualDocuments ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_PollIndividualDocumentsAsync.cs)
60+
61+
[README]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/README.md

‎sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample3_OperationsHistory.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Translation History
2+
This sample demonstrates how to get the history for all submitted translation operations on your Translator resource. To get started you will need a Translator endpoint and credentials. See [README][README] for links and instructions.
3+
4+
## Creating a `DocumentTranslationClient`
5+
6+
To create a new `DocumentTranslationClient` to run a translation operation for documents, you need a Translator endpoint and credentials. In the sample below, you'll use a Translator API key credential by creating an `AzureKeyCredential` object, that if needed, will allow you to update the API key without creating a new client.
7+
8+
You can set `endpoint` and `apiKey` based on an environment variable, a configuration setting, or any way that works for your application.
9+
10+
```C# Snippet:CreateDocumentTranslationClient
11+
string endpoint = "<endpoint>";
12+
string apiKey = "<apiKey>";
13+
var client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));
14+
```
15+
16+
## Getting all submitted translation operations
17+
18+
To get the Translation History, call `GetTranslationsAsync` which returns an AsyncPageable object containing the `TranslationStatusDetail` for all submitted translation operations.
19+
20+
The sample below gets the total number of documents translated in all submitted operations as well as the details of the operation contining the largest number of documents.
21+
22+
```C# Snippet:OperationsHistoryAsync
23+
int operationsCount = 0;
24+
int totalDocs = 0;
25+
int docsCancelled = 0;
26+
int docsSucceeded = 0;
27+
int docsFailed = 0;
28+
29+
await foreach (TranslationStatusDetail translationStatus in client.GetTranslationsAsync())
30+
{
31+
if (!translationStatus.HasCompleted)
32+
{
33+
DocumentTranslationOperation operation = new DocumentTranslationOperation(translationStatus.TranslationId, client);
34+
await operation.WaitForCompletionAsync();
35+
}
36+
37+
operationsCount++;
38+
totalDocs += translationStatus.DocumentsTotal;
39+
docsCancelled += translationStatus.DocumentsCancelled;
40+
docsSucceeded += translationStatus.DocumentsSucceeded;
41+
docsFailed += translationStatus.DocumentsFailed;
42+
}
43+
44+
Console.WriteLine($"# of operations: {operationsCount}");
45+
Console.WriteLine($"Total Documents: {totalDocs}");
46+
Console.WriteLine($"Succeeded Document: {docsSucceeded}");
47+
Console.WriteLine($"Failed Document: {docsFailed}");
48+
Console.WriteLine($"Cancelled Documents: {docsCancelled}");
49+
```
50+
51+
To see the full example source files, see:
52+
53+
* [Synchronously OperationsHistory ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_OperationsHistory.cs)
54+
* [Asynchronously OperationsHistory ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_OperationsHistoryAsync.cs)
55+
56+
[README]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/README.md

‎sdk/documenttranslation/Azure.AI.DocumentTranslation/samples/Sample4_MultipleConfigurations.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Translating Documents
2+
This sample demonstrates how to translate documents in multiple blob container to different languages simultaneously. To get started you will need a Translator endpoint and credentials. See [README][README] for links and instructions.
3+
4+
## Creating a `DocumentTranslationClient`
5+
6+
To create a new `DocumentTranslationClient` to run a translation operation for documents, you need a Translator endpoint and credentials. In the sample below, you'll use a Translator API key credential by creating an `AzureKeyCredential` object, that if needed, will allow you to update the API key without creating a new client.
7+
8+
You can set `endpoint` and `apiKey` based on an environment variable, a configuration setting, or any way that works for your application.
9+
10+
```C# Snippet:CreateDocumentTranslationClient
11+
string endpoint = "<endpoint>";
12+
string apiKey = "<apiKey>";
13+
var client = new DocumentTranslationClient(new Uri(endpoint), new AzureKeyCredential(apiKey));
14+
```
15+
16+
## Translating documents in multiple blob containers
17+
18+
To Start a translation operation for documents in multiple blob containers, call `StartTranslationAsync` with multiple configurations. The result is a Long Running operation of type `DocumentTranslationOperation` which polls for the status of the translation operation from the API.
19+
20+
To call `StartTranslationAsync` you need to initialize a list of `TranslationConfiguration` which contains the information needed to translate the documents. Each `TranslationConfiguration` contains a source container and a list of target containers. The `AddTarget` method is used to add targets to the configuration.
21+
22+
The `sourceUri` is a SAS URI with read access for the blob container holding the documents to be translated.
23+
The `targetUri` is a SAS URI with write access for the blob container to which the translated documents will be written.
24+
25+
More on generating SAS Tokens [here](https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/get-started-with-document-translation?tabs=csharp#create-sas-access-tokens-for-document-translation)
26+
27+
```C# Snippet:MultipleConfigurationsAsync
28+
Uri source1SasUriUri = <source1 SAS URI>;
29+
Uri source2SasUri = <source2 SAS URI>;
30+
Uri frenchTargetSasUri = <french target SAS URI>;
31+
Uri arabicTargetSasUri = <arabic target SAS URI>;
32+
Uri spanishTargetSasUri = <spanish target SAS URI>;
33+
Uri frenchGlossarySasUri = <french glossary SAS URI>;
34+
35+
var configuration1 = new TranslationConfiguration(source1SasUriUri, frenchTargetSasUri, "fr", new TranslationGlossary(frenchGlossarySasUri));
36+
configuration1.AddTarget(spanishTargetSasUri, "es");
37+
38+
var configuration2 = new TranslationConfiguration(source2SasUri, arabicTargetSasUri, "ar");
39+
configuration2.AddTarget(frenchTargetSasUri, "fr", new TranslationGlossary(frenchGlossarySasUri));
40+
41+
var inputs = new List<TranslationConfiguration>()
42+
{
43+
configuration1,
44+
configuration2
45+
};
46+
47+
DocumentTranslationOperation operation = await client.StartTranslationAsync(inputs);
48+
49+
TimeSpan pollingInterval = new TimeSpan(1000);
50+
51+
while (!operation.HasCompleted)
52+
{
53+
await Task.Delay(pollingInterval);
54+
await operation.UpdateStatusAsync();
55+
56+
Console.WriteLine($" Status: {operation.Status}");
57+
Console.WriteLine($" Created on: {operation.CreatedOn}");
58+
Console.WriteLine($" Last modified: {operation.LastModified}");
59+
Console.WriteLine($" Total documents: {operation.DocumentsTotal}");
60+
Console.WriteLine($" Succeeded: {operation.DocumentsSucceeded}");
61+
Console.WriteLine($" Failed: {operation.DocumentsFailed}");
62+
Console.WriteLine($" In Progress: {operation.DocumentsInProgress}");
63+
Console.WriteLine($" Not started: {operation.DocumentsNotStarted}");
64+
}
65+
66+
await foreach (DocumentStatusDetail document in operation.GetValuesAsync())
67+
{
68+
Console.WriteLine($"Document with Id: {document.DocumentId}");
69+
Console.WriteLine($" Status:{document.Status}");
70+
if (document.Status == TranslationStatus.Succeeded)
71+
{
72+
Console.WriteLine($" Location: {document.LocationUri}");
73+
Console.WriteLine($" Translated to language: {document.TranslateTo}.");
74+
}
75+
else
76+
{
77+
Console.WriteLine($" Error Code: {document.Error.ErrorCode}");
78+
Console.WriteLine($" Message: {document.Error.Message}");
79+
}
80+
}
81+
```
82+
83+
To see the full example source files, see:
84+
85+
* [Synchronously MultipleConfigurations ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_MultipleConfigurations.cs)
86+
* [Asynchronously MultipleConfigurations ](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/tests/samples/Sample_MultipleConfigurationsAsync.cs)
87+
88+
[README]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/documenttranslation/Azure.AI.DocumentTranslation/README.md

‎sdk/documenttranslation/Azure.AI.DocumentTranslation/src/TranslationConfiguration.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
// Licensed under the MIT License.
33

44
using System;
5+
using System.Collections.Generic;
56
using Azure.Core;
67

78
namespace Azure.AI.DocumentTranslation
@@ -27,7 +28,7 @@ public TranslationConfiguration(Uri sourceUri, Uri targetUri, string targetLangu
2728
{
2829
target.Glossaries.Add(glossary);
2930
}
30-
Targets.Add(target);
31+
Targets = new List<TranslationTarget> { target };
3132
}
3233

3334
/// <summary>

0 commit comments

Comments
 (0)