Skip to content

Commit

Permalink
[Text Translation] Options Parameter for Translate and Transliterate (#…
Browse files Browse the repository at this point in the history 
…38760)

* Options Parameter for Translate and Transliterate

* Remove empty options constructor, add new samples and recorded tests, update documentation.

* Update CHANGELOG.md and assets.json, fixed bug in TranslationLiveTests.cs

* Deleting unnecessary SessionRecords test files.

---------

Co-authored-by: Rango Meadows <[email protected]>
  • Loading branch information
@rangothedog
rangothedog and Rango Meadows committed Sep 28, 2023
1 parent f31c17e commit d086495
Show file tree
Hide file tree
Showing 13 changed files with 1,039 additions and 29 deletions.
1 change: 1 addition & 0 deletions sdk/translation/Azure.AI.Translation.Text/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
### Features Added

- Introduced model factory `Azure.AI.Translation.Text.TextTranslationModelFactory` for mocking.
- Added options overloads to Translate and Transliterate. TextTranslationTranslateOptions and TextTranslationTransliterateOptions roll up method parameters into a single object.

### Breaking Changes

Expand Down
86 changes: 83 additions & 3 deletions sdk/translation/Azure.AI.Translation.Text/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -123,8 +123,7 @@ For samples on using the `languages` endpoint refer to more samples [here][langu
Please refer to the service documentation for a conceptual discussion of [languages][languages_doc].

### Translate

Renders single source-language text to multiple target-language texts with a single request.
The simplest use of the Translate method is to invoke it with a single target language and one input string.

```C# Snippet:GetTextTranslation
try
Expand All @@ -146,6 +145,62 @@ catch (RequestFailedException exception)
}
```

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.

```C# Snippet:GetTextTranslationMatrixOptions
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?.Score}.");

Console.WriteLine($"Text was translated to: '{translation?.Translations?.FirstOrDefault().To}' 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.

```C# Snippet:GetTranslationTextTransliteratedOptions
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][translate_sample].

Please refer to the service documentation for a conceptual discussion of [translate][translate_doc].
Expand Down Expand Up @@ -176,6 +231,31 @@ catch (RequestFailedException exception)
}
```

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.

```C# Snippet:GetTransliteratedTextOptions
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][transliterate_sample].

Please refer to the service documentation for a conceptual discussion of [transliterate][transliterate_doc].
Expand All @@ -194,7 +274,7 @@ try
BreakSentenceItem brokenSentence = brokenSentences.FirstOrDefault();

Console.WriteLine($"Detected languages of the input text: {brokenSentence?.DetectedLanguage?.Language} with score: {brokenSentence?.DetectedLanguage?.Score}.");
Console.WriteLine($"The detected sentece boundaries: '{string.Join(",", brokenSentence?.SentLen)}'.");
Console.WriteLine($"The detected sentence boundaries: '{string.Join(",", brokenSentence?.SentLen)}'.");
}
catch (RequestFailedException exception)
{
Expand Down
34 changes: 34 additions & 0 deletions sdk/translation/Azure.AI.Translation.Text/api/Azure.AI.Translation.Text.netstandard2.0.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,14 +198,18 @@ protected TextTranslationClient(System.Uri endpoint, Azure.AI.Translation.Text.T
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.DictionaryExampleItem>> LookupDictionaryExamples(string from, string to, System.Collections.Generic.IEnumerable<Azure.AI.Translation.Text.InputTextWithTranslation> content, string clientTraceId = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.DictionaryExampleItem>>> LookupDictionaryExamplesAsync(string from, string to, Azure.AI.Translation.Text.InputTextWithTranslation content, string clientTraceId = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.DictionaryExampleItem>>> LookupDictionaryExamplesAsync(string from, string to, System.Collections.Generic.IEnumerable<Azure.AI.Translation.Text.InputTextWithTranslation> content, string clientTraceId = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>> Translate(Azure.AI.Translation.Text.TextTranslationTranslateOptions options, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>> Translate(System.Collections.Generic.IEnumerable<string> targetLanguages, System.Collections.Generic.IEnumerable<string> content, string clientTraceId = null, string sourceLanguage = null, Azure.AI.Translation.Text.TextType? textType = default(Azure.AI.Translation.Text.TextType?), string category = null, Azure.AI.Translation.Text.ProfanityAction? profanityAction = default(Azure.AI.Translation.Text.ProfanityAction?), Azure.AI.Translation.Text.ProfanityMarker? profanityMarker = default(Azure.AI.Translation.Text.ProfanityMarker?), bool? includeAlignment = default(bool?), bool? includeSentenceLength = default(bool?), string suggestedFrom = null, string fromScript = null, string toScript = null, bool? allowFallback = default(bool?), System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>> Translate(string targetLanguage, System.Collections.Generic.IEnumerable<string> content, string sourceLanguage = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>> Translate(string targetLanguage, string text, string sourceLanguage = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>>> TranslateAsync(Azure.AI.Translation.Text.TextTranslationTranslateOptions options, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>>> TranslateAsync(System.Collections.Generic.IEnumerable<string> targetLanguages, System.Collections.Generic.IEnumerable<string> content, string clientTraceId = null, string sourceLanguage = null, Azure.AI.Translation.Text.TextType? textType = default(Azure.AI.Translation.Text.TextType?), string category = null, Azure.AI.Translation.Text.ProfanityAction? profanityAction = default(Azure.AI.Translation.Text.ProfanityAction?), Azure.AI.Translation.Text.ProfanityMarker? profanityMarker = default(Azure.AI.Translation.Text.ProfanityMarker?), bool? includeAlignment = default(bool?), bool? includeSentenceLength = default(bool?), string suggestedFrom = null, string fromScript = null, string toScript = null, bool? allowFallback = default(bool?), System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>>> TranslateAsync(string targetLanguage, System.Collections.Generic.IEnumerable<string> content, string sourceLanguage = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TranslatedTextItem>>> TranslateAsync(string targetLanguage, string text, string sourceLanguage = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TransliteratedText>> Transliterate(Azure.AI.Translation.Text.TextTranslationTransliterateOptions options, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TransliteratedText>> Transliterate(string language, string fromScript, string toScript, System.Collections.Generic.IEnumerable<string> content, string clientTraceId = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TransliteratedText>> Transliterate(string language, string fromScript, string toScript, string text, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TransliteratedText>>> TransliterateAsync(Azure.AI.Translation.Text.TextTranslationTransliterateOptions options, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TransliteratedText>>> TransliterateAsync(string language, string fromScript, string toScript, System.Collections.Generic.IEnumerable<string> content, string clientTraceId = null, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
public virtual System.Threading.Tasks.Task<Azure.Response<System.Collections.Generic.IReadOnlyList<Azure.AI.Translation.Text.TransliteratedText>>> TransliterateAsync(string language, string fromScript, string toScript, string text, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
}
Expand All @@ -217,6 +221,36 @@ public enum ServiceVersion
V3_0 = 1,
}
}
public partial class TextTranslationTranslateOptions
{
public TextTranslationTranslateOptions(System.Collections.Generic.IEnumerable<string> targetLanguages, System.Collections.Generic.IEnumerable<string> content) { }
public TextTranslationTranslateOptions(System.Collections.Generic.IEnumerable<string> targetLanguages, System.Collections.Generic.IEnumerable<string> content, string clientTraceId = null, string sourceLanguage = null, Azure.AI.Translation.Text.TextType? textType = default(Azure.AI.Translation.Text.TextType?), string category = null, Azure.AI.Translation.Text.ProfanityAction? profanityAction = default(Azure.AI.Translation.Text.ProfanityAction?), Azure.AI.Translation.Text.ProfanityMarker? profanityMarker = default(Azure.AI.Translation.Text.ProfanityMarker?), bool? includeAlignment = default(bool?), bool? includeSentenceLength = default(bool?), string suggestedFrom = null, string fromScript = null, string toScript = null, bool? allowFallback = default(bool?)) { }
public TextTranslationTranslateOptions(string targetLanguage, string content) { }
public bool? AllowFallback { get { throw null; } set { } }
public string Category { get { throw null; } set { } }
public string ClientTraceId { get { throw null; } set { } }
public System.Collections.Generic.IEnumerable<string> Content { get { throw null; } }
public string FromScript { get { throw null; } set { } }
public bool? IncludeAlignment { get { throw null; } set { } }
public bool? IncludeSentenceLength { get { throw null; } set { } }
public Azure.AI.Translation.Text.ProfanityAction? ProfanityAction { get { throw null; } set { } }
public Azure.AI.Translation.Text.ProfanityMarker? ProfanityMarker { get { throw null; } set { } }
public string SourceLanguage { get { throw null; } set { } }
public string SuggestedFrom { get { throw null; } set { } }
public System.Collections.Generic.IEnumerable<string> TargetLanguages { get { throw null; } }
public Azure.AI.Translation.Text.TextType? TextType { get { throw null; } set { } }
public string ToScript { get { throw null; } set { } }
}
public partial class TextTranslationTransliterateOptions
{
public TextTranslationTransliterateOptions(string language, string fromScript, string toScript, System.Collections.Generic.IEnumerable<string> content, string clientTraceId = null) { }
public TextTranslationTransliterateOptions(string language, string fromScript, string toScript, string content, string clientTraceId = null) { }
public string ClientTraceId { get { throw null; } set { } }
public System.Collections.Generic.IEnumerable<string> Content { get { throw null; } }
public string FromScript { get { throw null; } }
public string Language { get { throw null; } }
public string ToScript { get { throw null; } }
}
[System.Runtime.InteropServices.StructLayoutAttribute(System.Runtime.InteropServices.LayoutKind.Sequential)]
public readonly partial struct TextType : System.IEquatable<Azure.AI.Translation.Text.TextType>
{
Expand Down
2 changes: 1 addition & 1 deletion sdk/translation/Azure.AI.Translation.Text/assets.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@
"AssetsRepo": "Azure/azure-sdk-assets",
"AssetsRepoPrefixPath": "net",
"TagPrefix": "net/translation/Azure.AI.Translation.Text",
"Tag": "net/translation/Azure.AI.Translation.Text_311c195b9c"
"Tag": "net/translation/Azure.AI.Translation.Text_9702e6ff9b"
}
Loading

0 comments on commit d086495

Please sign in to comment.