diff --git a/sdk/translation/Azure.AI.Translation.Document/README.md b/sdk/translation/Azure.AI.Translation.Document/README.md index 92857fd05e5f..4252d6370c6f 100644 --- a/sdk/translation/Azure.AI.Translation.Document/README.md +++ b/sdk/translation/Azure.AI.Translation.Document/README.md @@ -455,12 +455,12 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con [documenttranslation_nuget_package]: https://www.nuget.org/packages/Azure.AI.Translation.Document [documenttranslation_samples]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/translation/Azure.AI.Translation.Document/samples/README.md [documenttranslation_rest_api]: https://github.com/Azure/azure-rest-api-specs/blob/master/specification/cognitiveservices/data-plane/TranslatorText/stable/v1.0/TranslatorBatch.json -[custom_domain_endpoint]: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/get-started-with-document-translation?tabs=csharp#what-is-the-custom-domain-endpoint +[custom_domain_endpoint]: https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/quickstarts/document-translation-rest-api?pivots=programming-language-csharp#what-is-the-custom-domain-endpoint [single_service]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=singleservice%2Cwindows [azure_portal_create_DT_resource]: https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation [cognitive_resource_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli [dotnet_lro]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/README.md#consuming-long-running-operations-using-operationt -[source_containers]: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/get-started-with-document-translation?tabs=csharp#create-your-azure-blob-storage-containers +[source_containers]: https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/quickstarts/document-translation-rest-api?pivots=programming-language-csharp#create-azure-blob-storage-containers [custom_model]: https://docs.microsoft.com/azure/cognitive-services/translator/custom-translator/quickstart-build-deploy-custom-model [glossary]: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/overview#supported-glossary-formats [sas_token]: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/create-sas-tokens?tabs=Containers#create-your-sas-tokens-with-azure-storage-explorer diff --git a/sdk/translation/Azure.AI.Translation.Text/src/Custom/TextTranslationClient.cs b/sdk/translation/Azure.AI.Translation.Text/src/Custom/TextTranslationClient.cs index 022ce5466e35..423d09adbba2 100644 --- a/sdk/translation/Azure.AI.Translation.Text/src/Custom/TextTranslationClient.cs +++ b/sdk/translation/Azure.AI.Translation.Text/src/Custom/TextTranslationClient.cs @@ -9,6 +9,7 @@ using System.Threading; using System.Linq; using System.Text.Json; +using System.Security.Principal; namespace Azure.AI.Translation.Text { @@ -117,6 +118,173 @@ public TextTranslationClient(TokenCredential credential, Uri endpoint, TextTrans } } + /// Client options for TextTranslationClient.Translate + public partial class TextTranslationTranslateOptions : ClientOptions + { + /// + /// Specifies the language of the output text. The target language must be one of the supported languages included + /// in the translation scope. For example, use to=de to translate to German. + /// It's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. + /// For example, use to=de and to=it to translate to German and Italian. + /// + public IEnumerable TargetLanguages { get; set; } + /// + /// Array of the text to be translated. + /// + public IEnumerable Content { get; set; } + /// + /// A client-generated GUID to uniquely identify the request. + /// + public string ClientTraceId { get; set; } + /// + /// Specifies the language of the input text. Find which languages are available to translate from by + /// looking up supported languages using the translation scope. If the from parameter isn't specified, + /// automatic language detection is applied to determine the source language. + /// + /// You must use the from parameter rather than autodetection when using the dynamic dictionary feature. + /// Note: the dynamic dictionary feature is case-sensitive. + /// + public string SourceLanguage { get; set; } + /// + /// Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, + /// complete element. Possible values are: plain (default) or html. + /// + public TextType? TextType { get; set; } + /// + /// A string specifying the category (domain) of the translation. 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. + /// + public string Category { get; set; } + /// + /// Specifies how profanities should be treated in translations. + /// Possible values are: NoAction (default), Marked or Deleted. + /// + public ProfanityAction? ProfanityAction { get; set; } + /// + /// Specifies how profanities should be marked in translations. + /// Possible values are: Asterisk (default) or Tag. + /// + public ProfanityMarker? ProfanityMarker { get; set; } + /// + /// Specifies whether to include alignment projection from source text to translated text. + /// Possible values are: true or false (default). + /// + public bool? IncludeAlignment { get; set; } + /// + /// Specifies whether to include sentence boundaries for the input text and the translated text. + /// Possible values are: true or false (default). + /// + public bool? IncludeSentenceLength { get; set; } + /// + /// Specifies a fallback language if the language of the input text can't be identified. + /// Language autodetection is applied when the from parameter is omitted. If detection fails, + /// the SuggestedFrom language will be assumed. + /// + public string SuggestedFrom { get; set; } + /// + /// Specifies the script of the input text. + /// + public string FromScript { get; set; } + /// + /// Specifies the script of the translated text. + /// + public string ToScript { get; set; } + /// + /// Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. + /// Possible values are: true (default) or false. + /// + /// AllowFallback=false specifies that the translation should only use systems trained for the category specified + /// by the request. If a translation for language X to language Y requires chaining through a pivot language E, + /// then all the systems in the chain (X → E and E → Y) will need to be custom and have the same category. + /// If no system is found with the specific category, the request will return a 400 status code. AllowFallback=true + /// specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. + /// + public bool? AllowFallback { get; set; } + + /// Initializes new instance of TextTranslationTranslateOptions. + public TextTranslationTranslateOptions() + { + } + + /// Initializes new instance of TextTranslationTranslateOptions. + /// + /// Specifies the language of the output text. The target language must be one of the supported languages included + /// in the translation scope. For example, use to=de to translate to German. + /// It's possible to translate to multiple languages simultaneously by repeating the parameter in the query string. + /// For example, use to=de&to=it to translate to German and Italian. + /// + /// Array of the text to be translated. + /// A client-generated GUID to uniquely identify the request. + /// + /// Specifies the language of the input text. Find which languages are available to translate from by + /// looking up supported languages using the translation scope. If the from parameter isn't specified, + /// automatic language detection is applied to determine the source language. + /// + /// You must use the from parameter rather than autodetection when using the dynamic dictionary feature. + /// Note: the dynamic dictionary feature is case-sensitive. + /// + /// + /// Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, + /// complete element. Possible values are: plain (default) or html. + /// + /// + /// A string specifying the category (domain) of the translation. 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. + /// + /// + /// Specifies how profanities should be treated in translations. + /// Possible values are: NoAction (default), Marked or Deleted. + /// + /// + /// Specifies how profanities should be marked in translations. + /// Possible values are: Asterisk (default) or Tag. + /// + /// + /// Specifies whether to include alignment projection from source text to translated text. + /// Possible values are: true or false (default). + /// + /// + /// Specifies whether to include sentence boundaries for the input text and the translated text. + /// Possible values are: true or false (default). + /// + /// + /// Specifies a fallback language if the language of the input text can't be identified. + /// Language autodetection is applied when the from parameter is omitted. If detection fails, + /// the suggestedFrom language will be assumed. + /// + /// Specifies the script of the input text. + /// Specifies the script of the translated text. + /// + /// Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. + /// Possible values are: true (default) or false. + /// + /// allowFallback=false specifies that the translation should only use systems trained for the category specified + /// by the request. If a translation for language X to language Y requires chaining through a pivot language E, + /// then all the systems in the chain (X → E and E → Y) will need to be custom and have the same category. + /// If no system is found with the specific category, the request will return a 400 status code. allowFallback=true + /// specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. + /// + public TextTranslationTranslateOptions(IEnumerable targetLanguages, IEnumerable content, string clientTraceId = null, string sourceLanguage = null, TextType? textType = null, string category = null, ProfanityAction? profanityAction = null, ProfanityMarker? profanityMarker = null, bool? includeAlignment = null, bool? includeSentenceLength = null, string suggestedFrom = null, string fromScript = null, string toScript = null, bool? allowFallback = null) + { + TargetLanguages = targetLanguages; + Content = content; + ClientTraceId = clientTraceId; + SourceLanguage = sourceLanguage; + TextType = textType; + Category = category; + ProfanityAction = profanityAction; + ProfanityMarker = profanityMarker; + IncludeAlignment = includeAlignment; + IncludeSentenceLength = includeSentenceLength; + SuggestedFrom = suggestedFrom; + FromScript = fromScript; + ToScript = toScript; + AllowFallback = allowFallback; + } + } + /// Translate Text. /// /// Specifies the language of the output text. The target language must be one of the supported languages included @@ -186,6 +354,17 @@ public virtual Task>> TranslateAsync( return this.TranslateAsync(targetLanguages, content.Select(input => new InputTextItem(input)), clientTraceId, sourceLanguage, textType?.ToString(), category, profanityAction?.ToString(), profanityMarker?.ToString(), includeAlignment, includeSentenceLength, suggestedFrom, fromScript, toScript, allowFallback, cancellationToken); } + /// Translate Text. + /// The client translation options. + /// The cancellation token to use. + /// is null. + public virtual Task>> TranslateAsync(TextTranslationTranslateOptions options, CancellationToken cancellationToken = default) + { + Argument.AssertNotNull(options, nameof(options)); + + return this.TranslateAsync(options.TargetLanguages, options.Content.Select(input => new InputTextItem(input)), options.ClientTraceId, options.SourceLanguage, options.TextType?.ToString(), options.Category, options.ProfanityAction?.ToString(), options.ProfanityMarker?.ToString(), options.IncludeAlignment, options.IncludeSentenceLength, options.SuggestedFrom, options.FromScript, options.ToScript, options.AllowFallback, cancellationToken); + } + /// Translate Text. /// /// Specifies the language of the output text. The target language must be one of the supported languages included @@ -307,6 +486,17 @@ public virtual Response> Translate(IEnumerable return this.Translate(targetLanguages, content.Select(input => new InputTextItem(input)), clientTraceId, sourceLanguage, textType?.ToString(), category, profanityAction?.ToString(), profanityMarker?.ToString(), includeAlignment, includeSentenceLength, suggestedFrom, fromScript, toScript, allowFallback, cancellationToken); } + /// Translate Text. + /// The client translation options. + /// The cancellation token to use. + /// is null. + public virtual Response> Translate(TextTranslationTranslateOptions options, CancellationToken cancellationToken = default) + { + Argument.AssertNotNull(options, nameof(options)); + + return this.Translate(options.TargetLanguages, options.Content.Select(input => new InputTextItem(input)), options.ClientTraceId, options.SourceLanguage, options.TextType?.ToString(), options.Category, options.ProfanityAction?.ToString(), options.ProfanityMarker?.ToString(), options.IncludeAlignment, options.IncludeSentenceLength, options.SuggestedFrom, options.FromScript, options.ToScript, options.AllowFallback, cancellationToken); + } + /// Translate Text. /// /// Specifies the language of the output text. The target language must be one of the supported languages included @@ -359,6 +549,66 @@ public virtual Response> Translate(string targ return this.Translate(new[] { targetLanguage }, new[] { new InputTextItem(text) }, from: sourceLanguage, cancellationToken: cancellationToken); } + /// Client options for TextTranslationClient.Transliterate + public partial class TextTranslationTransliterateOptions : ClientOptions + { + /// + /// Specifies the language of the text to convert from one script to another. + /// Possible languages are listed in the transliteration scope obtained by querying the service + /// for its supported languages. + /// + public string Language { get; set; } + /// + /// Specifies the script used by the input text. Look up supported languages using the transliteration scope, + /// to find input scripts available for the selected language. + /// + public string FromScript { get; set; } + /// + /// Specifies the output script. Look up supported languages using the transliteration scope, to find output + /// scripts available for the selected combination of input language and input script. + /// + public string ToScript { get; set; } + /// + /// Array of the text to be transliterated. + /// + public IEnumerable Content { get; set; } + /// + /// A client-generated GUID to uniquely identify the request. + /// + public string ClientTraceId { get; set; } + + /// Initializes new instance of TextTranslationTransliterateOptions. + public TextTranslationTransliterateOptions() + { + } + + /// Initializes new instance of TextTranslationTransliterateOptions. + /// + /// Specifies the language of the text to convert from one script to another. + /// Possible languages are listed in the transliteration scope obtained by querying the service + /// for its supported languages. + /// + /// + /// Specifies the script used by the input text. Look up supported languages using the transliteration scope, + /// to find input scripts available for the selected language. + /// + /// + /// Specifies the output script. Look up supported languages using the transliteration scope, to find output + /// scripts available for the selected combination of input language and input script. + /// + /// Array of the text to be transliterated. + /// A client-generated GUID to uniquely identify the request. + public TextTranslationTransliterateOptions(string language, string fromScript, string toScript, IEnumerable content, string clientTraceId = null) + { + Language = language; + Content = content; + FromScript = fromScript; + ToScript = toScript; + Content = content; + ClientTraceId = clientTraceId; + } + } + /// Transliterate Text. /// /// Specifies the language of the text to convert from one script to another. @@ -387,6 +637,19 @@ public virtual Task>> TransliterateAs return this.TransliterateAsync(language, fromScript, toScript, content.Select(input => new InputTextItem(input)), clientTraceId, cancellationToken); } + /// + /// Transliterate Text. + /// + /// + /// + /// A representing the result of the asynchronous operation. + public virtual Task>> TransliterateAsync(TextTranslationTransliterateOptions options, CancellationToken cancellationToken = default) + { + Argument.AssertNotNull(options, nameof(options)); + + return this.TransliterateAsync(options.Language, options.FromScript, options.ToScript, options.Content.Select(input => new InputTextItem(input)), options.ClientTraceId, cancellationToken); + } + /// Transliterate Text. /// /// Specifies the language of the text to convert from one script to another. @@ -442,6 +705,17 @@ public virtual Response> Transliterate(string return this.Transliterate(language, fromScript, toScript, content.Select(input => new InputTextItem(input)), clientTraceId, cancellationToken); } + /// Transliterate Text. + /// The configuration options for the transliterate call. + /// The cancellation token to use. + /// is null. + public virtual Response> Transliterate(TextTranslationTransliterateOptions options, CancellationToken cancellationToken = default) + { + Argument.AssertNotNull(options, nameof(options)); + + return this.Transliterate(options.Language, options.FromScript, options.ToScript, options.Content.Select(input => new InputTextItem(input)), options.ClientTraceId, cancellationToken); + } + /// Transliterate Text. /// /// Specifies the language of the text to convert from one script to another.