diff --git a/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/GetSupportedLanguages_MaximumSet_Gen.json b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/GetSupportedLanguages_MaximumSet_Gen.json new file mode 100644 index 000000000000..6f8272101b23 --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/GetSupportedLanguages_MaximumSet_Gen.json @@ -0,0 +1,80 @@ +{ + "title": "Gets the set of languages currently supported by other operations of the Translator.", + "operationId": "GetSupportedLanguages", + "parameters": { + "X-ClientTraceId": "kayfnugjec", + "scope": "translation,transliteration,dictionary", + "Accept-Language": "en", + "If-None-Match": "fpnhruttllvc", + "api-version": "2025-10-01-preview" + }, + "responses": { + "200": { + "body": { + "translation": { + "en": { + "name": "English", + "nativeName": "English", + "dir": "ltr" + }, + "es": { + "name": "Spanish", + "nativeName": "Español", + "dir": "ltr" + } + }, + "transliteration": { + "ar": { + "name": "Arabic", + "nativeName": "العربية", + "scripts": [ + { + "code": "Arab", + "name": "Arabic", + "nativeName": "العربية", + "dir": "rtl", + "toScripts": [ + { + "code": "Latn", + "name": "Latin", + "nativeName": "اللاتينية", + "dir": "ltr" + } + ] + }, + { + "code": "Latn", + "name": "Latin", + "nativeName": "اللاتينية", + "dir": "ltr", + "toScripts": [ + { + "code": "Arab", + "name": "Arabic", + "nativeName": "العربية", + "dir": "rtl" + } + ] + } + ] + } + }, + "dictionary": { + "cs": { + "name": "Czech", + "nativeName": "Čeština", + "dir": "ltr", + "translations": [ + { + "name": "English", + "nativeName": "English", + "dir": "ltr", + "code": "en" + } + ] + } + } + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/GetSupportedLanguages_MinimumSet_Gen.json b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/GetSupportedLanguages_MinimumSet_Gen.json new file mode 100644 index 000000000000..2d8fd62fd176 --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/GetSupportedLanguages_MinimumSet_Gen.json @@ -0,0 +1,12 @@ +{ + "title": "Gets the set of languages currently supported by other operations of the Translator with minimum properties.", + "operationId": "GetSupportedLanguages", + "parameters": { + "api-version": "2025-10-01-preview" + }, + "responses": { + "200": { + "body": {} + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Translate_MaximumSet_Gen.json b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Translate_MaximumSet_Gen.json new file mode 100644 index 000000000000..0d9060d8ea04 --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Translate_MaximumSet_Gen.json @@ -0,0 +1,62 @@ +{ + "title": "Translate Text", + "operationId": "Translate", + "parameters": { + "X-ClientTraceId": "ndbkaatzsnoetqkiehappoza", + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "This is a test.", + "script": "Latn", + "language": "en", + "textType": "Plain", + "targets": [ + { + "language": "cs", + "script": "Latn", + "profanityAction": "NoAction", + "profanityMarker": "Asterisk", + "deploymentName": "gpt-4o-mini", + "allowFallback": true, + "grade": "basic", + "tone": "formal", + "gender": "neutral", + "adaptiveDatasetId": "21000", + "referenceTextPairs": [ + { + "source": "Please test this out.", + "target": "Vyzkoušejte si to." + } + ] + } + ] + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "detectedLanguage": { + "language": "en", + "score": 1.0 + }, + "translations": [ + { + "language": "cs", + "instructionTokens": 302, + "sourceTokens": 5, + "responseTokens": 9, + "targetTokens": 5, + "text": "Toto je test." + } + ] + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Translate_MinimumSet_Gen.json b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Translate_MinimumSet_Gen.json new file mode 100644 index 000000000000..ce1b820b1f5f --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Translate_MinimumSet_Gen.json @@ -0,0 +1,40 @@ +{ + "title": "Translate Text with minimum properties", + "operationId": "Translate", + "parameters": { + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "This is a test.", + "targets": [ + { + "language": "cs" + } + ] + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "detectedLanguage": { + "language": "en", + "score": 0.12345 + }, + "translations": [ + { + "language": "cs", + "sourceCharacters": 15, + "text": "Tohle je test." + } + ] + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Transliterate_MaximumSet_Gen.json b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Transliterate_MaximumSet_Gen.json new file mode 100644 index 000000000000..7be9e729071f --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Transliterate_MaximumSet_Gen.json @@ -0,0 +1,30 @@ +{ + "title": "Transliterate Text", + "operationId": "Transliterate", + "parameters": { + "X-ClientTraceId": "dzncrimwmvtwjnheh", + "language": "zh-Hans", + "fromScript": "Hans", + "toScript": "Latn", + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "这是个测试。" + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "text": "zhè shì gè cè shì。", + "script": "Latn" + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Transliterate_MinimumSet_Gen.json b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Transliterate_MinimumSet_Gen.json new file mode 100644 index 000000000000..b957d5852e0b --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/examples/2025-10-01-preview/Transliterate_MinimumSet_Gen.json @@ -0,0 +1,29 @@ +{ + "title": "Transliterate Text with minimum properties", + "operationId": "Transliterate", + "parameters": { + "language": "zh-Hans", + "fromScript": "Hans", + "toScript": "Latn", + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "这是个测试。" + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "text": "zhè shì gè cè shì。", + "script": "Latn" + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/main.tsp b/specification/translation/data-plane/TextTranslation/main.tsp index 8fcc8ff994da..2614c8bccbb9 100644 --- a/specification/translation/data-plane/TextTranslation/main.tsp +++ b/specification/translation/data-plane/TextTranslation/main.tsp @@ -3,9 +3,7 @@ import "@typespec/versioning"; import "@azure-tools/typespec-azure-core"; import "./routes.tsp"; -using TypeSpec.Rest; using TypeSpec.Http; -using Azure.Core; using TypeSpec.Versioning; #suppress "@azure-tools/typespec-azure-core/auth-required" "!!FIXME!!" @@ -35,10 +33,6 @@ using TypeSpec.Versioning; Transliterate. Converts characters or letters of a source language to the corresponding characters or letters of a target language. Detect. Returns the source code language code and a boolean variable denoting whether the detected language is supported for text translation and transliteration. - - Dictionary lookup. Returns equivalent words for the source term in the target language. - - Dictionary example Returns grammatical structure and context examples for the source term and target term pair. """) @versioned(APIVersion) namespace TextTranslation; @@ -47,4 +41,7 @@ namespace TextTranslation; enum APIVersion { @doc("Version 3.0") v3_0: "3.0", + + @doc("Version 2025-10-01") + v2025_10_01_preview: "2025-10-01-preview", } diff --git a/specification/translation/data-plane/TextTranslation/models-breaksentence.tsp b/specification/translation/data-plane/TextTranslation/models-breaksentence.tsp index 06798cb40010..f1dd5284077f 100644 --- a/specification/translation/data-plane/TextTranslation/models-breaksentence.tsp +++ b/specification/translation/data-plane/TextTranslation/models-breaksentence.tsp @@ -5,11 +5,13 @@ import "./models-translate.tsp"; using TypeSpec.Http; using TypeSpec.Rest; +using TypeSpec.Versioning; using Azure.Core; namespace TextTranslation; @doc("Request parameters for the break sentence API.") +@removed(APIVersion.v2025_10_01_preview) model BreakSentenceParameters { ...CommonParameters; @@ -29,6 +31,7 @@ model BreakSentenceParameters { } @doc("Response for the Break SEntence API.") +@removed(APIVersion.v2025_10_01_preview) model BreakSentenceResult { ...CommonResultHeaders; @@ -38,6 +41,7 @@ model BreakSentenceResult { } @doc("Item containing break sentence result.") +@removed(APIVersion.v2025_10_01_preview) model BreakSentenceItem { @doc("The detectedLanguage property is only present in the result object when language auto-detection is requested.") detectedLanguage?: DetectedLanguage; diff --git a/specification/translation/data-plane/TextTranslation/models-dictionary.tsp b/specification/translation/data-plane/TextTranslation/models-dictionary.tsp index 57f11e35e4de..bafc64d50ffa 100644 --- a/specification/translation/data-plane/TextTranslation/models-dictionary.tsp +++ b/specification/translation/data-plane/TextTranslation/models-dictionary.tsp @@ -4,10 +4,12 @@ import "./models-shared.tsp"; using TypeSpec.Http; using TypeSpec.Rest; +using TypeSpec.Versioning; using Azure.Core; namespace TextTranslation; +@removed(APIVersion.v2025_10_01_preview) @doc("Request parameters for the dictionary lookup API.") model DictionaryLookupParameters { ...CommonParameters; @@ -27,6 +29,7 @@ model DictionaryLookupParameters { to: string; } +@removed(APIVersion.v2025_10_01_preview) @doc("Request parameters for the dictionary examples API.") model DictionaryExamplesParameters { ...CommonParameters; @@ -46,6 +49,7 @@ model DictionaryExamplesParameters { to: string; } +@removed(APIVersion.v2025_10_01_preview) @doc("Response for the dictionary lookup API.") model DictionaryLookupResult { ...CommonResultHeaders; @@ -55,6 +59,7 @@ model DictionaryLookupResult { result: DictionaryLookupItem[]; } +@removed(APIVersion.v2025_10_01_preview) @doc("Response for the dictionary examples API.") model DictionaryExamplesResult { ...CommonResultHeaders; @@ -65,6 +70,7 @@ model DictionaryExamplesResult { } @doc("Element containing the text with translation.") +@removed(APIVersion.v2025_10_01_preview) model DictionaryExampleTextItem extends InputTextItem { @doc(""" A string specifying the translated text previously returned by the Dictionary lookup operation. @@ -74,6 +80,7 @@ model DictionaryExampleTextItem extends InputTextItem { translation: string; } +@removed(APIVersion.v2025_10_01_preview) @doc("Dictionary Lookup Element") model DictionaryLookupItem { @doc(""" @@ -96,6 +103,7 @@ model DictionaryLookupItem { translations: DictionaryTranslation[]; } +@removed(APIVersion.v2025_10_01_preview) @doc("Translation source term.") model DictionaryTranslation { @doc(""" @@ -142,6 +150,7 @@ model DictionaryTranslation { backTranslations: BackTranslation[]; } +@removed(APIVersion.v2025_10_01_preview) @doc("Back Translation") model BackTranslation { @doc(""" @@ -174,6 +183,7 @@ model BackTranslation { frequencyCount: int32; } +@removed(APIVersion.v2025_10_01_preview) @doc("Dictionary Example element") model DictionaryExampleItem { @doc(""" @@ -194,6 +204,7 @@ model DictionaryExampleItem { examples: DictionaryExample[]; } +@removed(APIVersion.v2025_10_01_preview) @doc("Dictionary Example") model DictionaryExample { @doc(""" diff --git a/specification/translation/data-plane/TextTranslation/models-shared.tsp b/specification/translation/data-plane/TextTranslation/models-shared.tsp index 87df889e0c2b..107e4a75b04f 100644 --- a/specification/translation/data-plane/TextTranslation/models-shared.tsp +++ b/specification/translation/data-plane/TextTranslation/models-shared.tsp @@ -3,6 +3,7 @@ import "@azure-tools/typespec-azure-core"; using TypeSpec.Http; using TypeSpec.Rest; +using TypeSpec.Versioning; using Azure.Core; namespace TextTranslation; @@ -40,8 +41,14 @@ model ErrorResponse { @doc("Error details as returned by Translator Service.") model ErrorDetails { + @removed(APIVersion.v2025_10_01_preview) + @renamedFrom(APIVersion.v2025_10_01_preview, "code") @doc("Number identifier of the error.") - code: int32; + codeV3: int32; + + @added(APIVersion.v2025_10_01_preview) + @doc("String identifier of the error.") + code: string; @doc("Human readable error description.") message: string; diff --git a/specification/translation/data-plane/TextTranslation/models-translate.tsp b/specification/translation/data-plane/TextTranslation/models-translate.tsp index bb58e8f185f8..9f47ded25e64 100644 --- a/specification/translation/data-plane/TextTranslation/models-translate.tsp +++ b/specification/translation/data-plane/TextTranslation/models-translate.tsp @@ -1,10 +1,11 @@ import "@typespec/rest"; +import "@typespec/versioning"; import "@azure-tools/typespec-azure-core"; import "./models-shared.tsp"; import "./models-transliterate.tsp"; using TypeSpec.Http; -using TypeSpec.Rest; +using TypeSpec.Versioning; using Azure.Core; namespace TextTranslation; @@ -14,6 +15,7 @@ model TranslateParameters { ...CommonParameters; #suppress "@azure-tools/typespec-azure-core/no-query-explode" "Existing Spec" + @removed(APIVersion.v2025_10_01_preview) @query(#{ explode: true }) @doc(""" Specifies the language of the output text. The target language must be one of the supported languages included @@ -23,6 +25,7 @@ model TranslateParameters { """) to: string[]; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies the language of the input text. Find which languages are available to translate from by @@ -34,6 +37,7 @@ model TranslateParameters { """) from?: string; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, @@ -41,6 +45,7 @@ model TranslateParameters { """) textType?: TextType = "Plain"; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" A string specifying the category (domain) of the translation. This parameter is used to get translations @@ -49,6 +54,7 @@ model TranslateParameters { """) category?: string = "general"; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies how profanities should be treated in translations. @@ -56,6 +62,7 @@ model TranslateParameters { """) profanityAction?: ProfanityAction = ProfanityAction.NoAction; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies how profanities should be marked in translations. @@ -63,6 +70,7 @@ model TranslateParameters { """) profanityMarker?: ProfanityMarker = ProfanityMarker.Asterisk; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies whether to include alignment projection from source text to translated text. @@ -70,6 +78,7 @@ model TranslateParameters { """) includeAlignment?: boolean = false; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies whether to include sentence boundaries for the input text and the translated text. @@ -77,6 +86,7 @@ model TranslateParameters { """) includeSentenceLength?: boolean = false; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies a fallback language if the language of the input text can't be identified. @@ -85,18 +95,21 @@ model TranslateParameters { """) suggestedFrom?: string; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies the script of the input text. """) fromScript?: string; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies the script of the translated text. """) toScript?: string; + @removed(APIVersion.v2025_10_01_preview) @query @doc(""" Specifies that the service is allowed to fall back to a general system when a custom system doesn't exist. @@ -111,8 +124,141 @@ model TranslateParameters { allowFallback?: boolean = true; } +@doc("Translate targets parameters") +@added(APIVersion.v2025_10_01_preview) +model TranslateTarget { + @doc(""" + Specifies the language of the output text. The target language must be one of the supported languages included + in the translation scope. It's possible to translate to multiple languages simultaneously by including + multiple string values in the targetsLanguage array. + """) + language: string; + + @doc(""" + Specifies the script of the translated text. + """) + script?: string; + + @doc(""" + Specifies how profanities should be treated in translations. + Possible values are: NoAction (default), Marked or Deleted. + """) + profanityAction?: ProfanityAction = ProfanityAction.NoAction; + + @doc(""" + Specifies how profanities should be marked in translations. + Possible values are: Asterisk (default) or Tag. + """) + profanityMarker?: ProfanityMarker = ProfanityMarker.Asterisk; + + @doc(""" + Default is ‘general’, which uses NMT system. + ‘abc-inc-gpt-4o’, and ‘abc-inc-gpt-4o-mini’ are examples of deployment names which use GPT-4o uses or + GPT-4o-mini model. ‘gpt-4o’ uses GPT-4o model. + + ‘’ uses the custom NMT model tuned by customer. + ‘best’ system determines which is the best model to use for the request. This intelligence could be introduced + in future. Customer should have deployed it in their resource. + + """) + deploymentName?: string = "general"; + + @doc(""" + In the case where a custom system is being used, specifies that the service is allowed to fall back to a + general system when a custom system doesn't exist. + In the case where a Large Language Model is being used, specifies that the service is allowed to fall + back to a Small Language Model if an error occurs. + 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. + """) + allowFallback?: boolean = true; + + @doc(""" + Defines complexity of LLM prompts to provide high accuracy translation. + """) + grade?: string = "basic"; + + @doc(""" + Desired tone of target translation. + """) + tone?: string; + + @doc(""" + Desired gender of target translation. + """) + gender?: string; + + @doc(""" + Reference dataset ID having sentence pair to generate adaptive customized translation. + """) + adaptiveDatasetId?: string; + + @doc(""" + Reference sentence pairs to generate adaptive results. + """) + @maxItems(5) + referenceTextPairs?: ReferenceSentencePair[]; +} + +@doc("Request body for the translate API.") +@added(APIVersion.v2025_10_01_preview) +model TranslateBody { + @doc("Array of the input text elements to translate.") + inputs: TranslateInputItem[]; +} + +@doc("Element containing the text for translation.") +@added(APIVersion.v2025_10_01_preview) +model TranslateInputItem { + @doc("Text to translate.") + text: string; + + @doc(""" + Specifies the script of the input text. + """) + script?: string; + + @doc(""" + Specifies the language of the input text. Find which languages are available to translate by + looking up supported languages using the translation scope. If the language parameter isn't + specified, automatic language detection is applied to determine the source language. + + You must use the language parameter rather than autodetection when using the dynamic dictionary feature. + Note: the dynamic dictionary feature is case-sensitive. + """) + language?: string; + + @doc(""" + 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. + """) + textType?: TextType = "Plain"; + + @doc(""" + Translation target parameters. + """) + targets: TranslateTarget[]; +} + +@doc("Reference sentence pair.") +@added(APIVersion.v2025_10_01_preview) +model ReferenceSentencePair { + @doc("Source reference sentence.") + source: string; + + @doc("Target reference sentence.") + target: string; +} + @doc("Response for the translation API.") -model TranslationResult { +@renamedFrom(APIVersion.v2025_10_01_preview, "TranslationResult") +@removed(APIVersion.v2025_10_01_preview) +model TranslationResultV3 { ...CommonResultHeaders; @bodyRoot @@ -138,6 +284,33 @@ model TranslationResult { meteredUsage: int32; } +@doc("Response for the translation API.") +@added(APIVersion.v2025_10_01_preview) +model TranslationResult { + ...CommonResultHeaders; + + @doc("Array of the translated text elements.") + value: TranslatedTextItem[]; + + @header("x-mt-system") + @doc(""" + Specifies the system type that was used for translation for each 'to' language requested for translation. + The value is a comma-separated list of strings. Each string indicates a type: + + * Custom - Request includes a custom system and at least one custom system was used during translation. + * Team - All other requests + """) + mtSystem: string; + + @header("x-metered-usage") + @doc(""" + Specifies consumption (the number of characters for which the user will be charged) for the translation + job request. For example, if the word "Hello" is translated from English (en) to French (fr), + this field will return the value '5'. + """) + meteredUsage: int32; +} + @doc("Translation text type") union TextType { string, @@ -183,6 +356,7 @@ model TranslatedTextItem { """) translations: TranslationText[]; + @removed(APIVersion.v2025_10_01_preview) @doc(""" Input text in the default script of the source language. sourceText property is present only when the input is expressed in a script that's not the usual script for the language. For example, @@ -206,28 +380,57 @@ model DetectedLanguage { @doc("Translation result") model TranslationText { + @removed(APIVersion.v2025_10_01_preview) @doc("A string representing the language code of the target language.") to: string; + @added(APIVersion.v2025_10_01_preview) + @doc("A string representing the language code of the target language.") + language: string; + + @added(APIVersion.v2025_10_01_preview) + @doc("An interger indicating the number of characters in the source text string") + sourceCharacters?: int32; + + @added(APIVersion.v2025_10_01_preview) + @doc("An interger indicating the number of tokens used in generating the translated text") + instructionTokens?: int32; + + @added(APIVersion.v2025_10_01_preview) + @doc("An interger indicating the number of tokens used in the source sentence") + sourceTokens?: int32; + + @added(APIVersion.v2025_10_01_preview) + @doc("An interger indicating the number of tokens used in the translation response") + responseTokens?: int32; + + @added(APIVersion.v2025_10_01_preview) + @doc("An interger indicating the number of tokens used in the target sentence") + targetTokens?: int32; + @doc("A string giving the translated text.") text: string; + @removed(APIVersion.v2025_10_01_preview) @doc(""" An object giving the translated text in the script specified by the toScript parameter. """) transliteration?: TransliteratedText; + @removed(APIVersion.v2025_10_01_preview) @doc(""" Alignment information. """) alignment?: TranslatedTextAlignment; + @removed(APIVersion.v2025_10_01_preview) @doc(""" Sentence boundaries in the input and output texts. """) sentLen?: SentenceBoundaries; } +@removed(APIVersion.v2025_10_01_preview) @doc("Alignment information object.") model TranslatedTextAlignment { @doc(""" @@ -241,6 +444,7 @@ model TranslatedTextAlignment { proj: string; } +@removed(APIVersion.v2025_10_01_preview) @doc("An object returning sentence boundaries in the input and output texts.") model SentenceBoundaries { @doc(""" @@ -256,6 +460,7 @@ model SentenceBoundaries { transSentLen: int32[]; } +@removed(APIVersion.v2025_10_01_preview) @doc("Input text in the default script of the source language. ") model SourceText { @doc(""" diff --git a/specification/translation/data-plane/TextTranslation/models-transliterate.tsp b/specification/translation/data-plane/TextTranslation/models-transliterate.tsp index a54e676a23a7..3fd9d4fec5a3 100644 --- a/specification/translation/data-plane/TextTranslation/models-transliterate.tsp +++ b/specification/translation/data-plane/TextTranslation/models-transliterate.tsp @@ -4,6 +4,7 @@ import "./models-shared.tsp"; using TypeSpec.Http; using TypeSpec.Rest; +using TypeSpec.Versioning; using Azure.Core; namespace TextTranslation; @@ -35,8 +36,17 @@ model TransliterateParameters { toScript: string; } +@doc("Request body for the transliterate API.") +@added(APIVersion.v2025_10_01_preview) +model TransliterateBody { + @doc("Array of the input text elements to transliterate.") + inputs: InputTextItem[]; +} + @doc("Response for the transliteration API.") -model TransliterateResult { +@renamedFrom(APIVersion.v2025_10_01_preview, "TransliterateResult") +@removed(APIVersion.v2025_10_01_preview) +model TransliterateResultV3 { ...CommonResultHeaders; @bodyRoot @@ -44,6 +54,15 @@ model TransliterateResult { result: TransliteratedText[]; } +@doc("Response for the transliteration API.") +@added(APIVersion.v2025_10_01_preview) +model TransliterateResult { + ...CommonResultHeaders; + + @doc("Array of transliterated texts") + value: TransliteratedText[]; +} + @doc("Transliterated text element.") model TransliteratedText { @doc("A string which is the result of converting the input string to the output script.") diff --git a/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/GetSupportedLanguages_MaximumSet_Gen.json b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/GetSupportedLanguages_MaximumSet_Gen.json new file mode 100644 index 000000000000..6f8272101b23 --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/GetSupportedLanguages_MaximumSet_Gen.json @@ -0,0 +1,80 @@ +{ + "title": "Gets the set of languages currently supported by other operations of the Translator.", + "operationId": "GetSupportedLanguages", + "parameters": { + "X-ClientTraceId": "kayfnugjec", + "scope": "translation,transliteration,dictionary", + "Accept-Language": "en", + "If-None-Match": "fpnhruttllvc", + "api-version": "2025-10-01-preview" + }, + "responses": { + "200": { + "body": { + "translation": { + "en": { + "name": "English", + "nativeName": "English", + "dir": "ltr" + }, + "es": { + "name": "Spanish", + "nativeName": "Español", + "dir": "ltr" + } + }, + "transliteration": { + "ar": { + "name": "Arabic", + "nativeName": "العربية", + "scripts": [ + { + "code": "Arab", + "name": "Arabic", + "nativeName": "العربية", + "dir": "rtl", + "toScripts": [ + { + "code": "Latn", + "name": "Latin", + "nativeName": "اللاتينية", + "dir": "ltr" + } + ] + }, + { + "code": "Latn", + "name": "Latin", + "nativeName": "اللاتينية", + "dir": "ltr", + "toScripts": [ + { + "code": "Arab", + "name": "Arabic", + "nativeName": "العربية", + "dir": "rtl" + } + ] + } + ] + } + }, + "dictionary": { + "cs": { + "name": "Czech", + "nativeName": "Čeština", + "dir": "ltr", + "translations": [ + { + "name": "English", + "nativeName": "English", + "dir": "ltr", + "code": "en" + } + ] + } + } + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/GetSupportedLanguages_MinimumSet_Gen.json b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/GetSupportedLanguages_MinimumSet_Gen.json new file mode 100644 index 000000000000..2d8fd62fd176 --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/GetSupportedLanguages_MinimumSet_Gen.json @@ -0,0 +1,12 @@ +{ + "title": "Gets the set of languages currently supported by other operations of the Translator with minimum properties.", + "operationId": "GetSupportedLanguages", + "parameters": { + "api-version": "2025-10-01-preview" + }, + "responses": { + "200": { + "body": {} + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Translate_MaximumSet_Gen.json b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Translate_MaximumSet_Gen.json new file mode 100644 index 000000000000..0d9060d8ea04 --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Translate_MaximumSet_Gen.json @@ -0,0 +1,62 @@ +{ + "title": "Translate Text", + "operationId": "Translate", + "parameters": { + "X-ClientTraceId": "ndbkaatzsnoetqkiehappoza", + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "This is a test.", + "script": "Latn", + "language": "en", + "textType": "Plain", + "targets": [ + { + "language": "cs", + "script": "Latn", + "profanityAction": "NoAction", + "profanityMarker": "Asterisk", + "deploymentName": "gpt-4o-mini", + "allowFallback": true, + "grade": "basic", + "tone": "formal", + "gender": "neutral", + "adaptiveDatasetId": "21000", + "referenceTextPairs": [ + { + "source": "Please test this out.", + "target": "Vyzkoušejte si to." + } + ] + } + ] + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "detectedLanguage": { + "language": "en", + "score": 1.0 + }, + "translations": [ + { + "language": "cs", + "instructionTokens": 302, + "sourceTokens": 5, + "responseTokens": 9, + "targetTokens": 5, + "text": "Toto je test." + } + ] + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Translate_MinimumSet_Gen.json b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Translate_MinimumSet_Gen.json new file mode 100644 index 000000000000..ce1b820b1f5f --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Translate_MinimumSet_Gen.json @@ -0,0 +1,40 @@ +{ + "title": "Translate Text with minimum properties", + "operationId": "Translate", + "parameters": { + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "This is a test.", + "targets": [ + { + "language": "cs" + } + ] + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "detectedLanguage": { + "language": "en", + "score": 0.12345 + }, + "translations": [ + { + "language": "cs", + "sourceCharacters": 15, + "text": "Tohle je test." + } + ] + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Transliterate_MaximumSet_Gen.json b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Transliterate_MaximumSet_Gen.json new file mode 100644 index 000000000000..7be9e729071f --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Transliterate_MaximumSet_Gen.json @@ -0,0 +1,30 @@ +{ + "title": "Transliterate Text", + "operationId": "Transliterate", + "parameters": { + "X-ClientTraceId": "dzncrimwmvtwjnheh", + "language": "zh-Hans", + "fromScript": "Hans", + "toScript": "Latn", + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "这是个测试。" + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "text": "zhè shì gè cè shì。", + "script": "Latn" + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Transliterate_MinimumSet_Gen.json b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Transliterate_MinimumSet_Gen.json new file mode 100644 index 000000000000..b957d5852e0b --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/examples/Transliterate_MinimumSet_Gen.json @@ -0,0 +1,29 @@ +{ + "title": "Transliterate Text with minimum properties", + "operationId": "Transliterate", + "parameters": { + "language": "zh-Hans", + "fromScript": "Hans", + "toScript": "Latn", + "api-version": "2025-10-01-preview", + "body": { + "inputs": [ + { + "text": "这是个测试。" + } + ] + } + }, + "responses": { + "200": { + "body": { + "value": [ + { + "text": "zhè shì gè cè shì。", + "script": "Latn" + } + ] + } + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/openapi.json b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/openapi.json new file mode 100644 index 000000000000..9fa50612847b --- /dev/null +++ b/specification/translation/data-plane/TextTranslation/preview/2025-10-01-preview/openapi.json @@ -0,0 +1,999 @@ +{ + "swagger": "2.0", + "info": { + "title": "Text Translation", + "version": "2025-10-01-preview", + "description": "Text translation is a cloud-based REST API feature of the Translator service that uses neural\nmachine translation technology to enable quick and accurate source-to-target text translation\nin real time across all supported languages.\n\nThe following methods are supported by the Text Translation feature:\n\nLanguages. Returns a list of languages supported by Translate, Transliterate, and Dictionary Lookup operations.\n\nTranslate. Renders single source-language text to multiple target-language texts with a single request.\n\nTransliterate. Converts characters or letters of a source language to the corresponding characters or letters of a target language.\n\nDetect. Returns the source code language code and a boolean variable denoting whether the detected language is supported for text translation and transliteration.", + "x-typespec-generated": [ + { + "emitter": "@azure-tools/typespec-autorest" + } + ] + }, + "schemes": [ + "https" + ], + "x-ms-parameterized-host": { + "hostTemplate": "{Endpoint}", + "useSchemePrefix": false, + "parameters": [ + { + "name": "Endpoint", + "in": "path", + "description": "Supported Text Translation endpoints (protocol and hostname, for example:\n https://api.cognitive.microsofttranslator.com).", + "required": true, + "type": "string", + "format": "uri", + "x-ms-skip-url-encoding": true + } + ] + }, + "produces": [ + "application/json" + ], + "consumes": [ + "application/json" + ], + "tags": [], + "paths": { + "/languages": { + "get": { + "operationId": "GetSupportedLanguages", + "summary": "Gets the set of languages currently supported by other operations of the Translator.", + "description": "Gets the set of languages currently supported by other operations of the Translator.", + "parameters": [ + { + "name": "X-ClientTraceId", + "in": "header", + "description": "A client-generated GUID to uniquely identify the request.", + "required": false, + "type": "string", + "x-ms-client-name": "clientTraceId" + }, + { + "$ref": "#/parameters/GetSupportedLanguagesParameters.scope" + }, + { + "$ref": "#/parameters/GetSupportedLanguagesParameters.acceptLanguage" + }, + { + "$ref": "#/parameters/GetSupportedLanguagesParameters.ifNoneMatch" + }, + { + "name": "api-version", + "in": "query", + "description": "Mandatory API version parameter", + "required": true, + "type": "string", + "x-ms-client-name": "apiVersion" + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "schema": { + "$ref": "#/definitions/GetSupportedLanguagesResult" + }, + "headers": { + "ETag": { + "type": "string", + "description": "Current value of the entity tag for the requested groups of supported languages. \nTo make subsequent requests more efficient, the client may send the `ETag` value in an \n`If-None-Match` header field." + }, + "X-RequestId": { + "type": "string", + "description": "Value generated by the service to identify the request. It is used for troubleshooting purposes." + } + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "headers": { + "X-RequestId": { + "type": "string", + "description": "Value generated by the service to identify the request. It is used for troubleshooting purposes." + } + } + } + }, + "x-ms-examples": { + "Gets the set of languages currently supported by other operations of the Translator with minimum properties.": { + "$ref": "./examples/GetSupportedLanguages_MinimumSet_Gen.json" + }, + "Gets the set of languages currently supported by other operations of the Translator.": { + "$ref": "./examples/GetSupportedLanguages_MaximumSet_Gen.json" + } + } + } + }, + "/translate": { + "post": { + "operationId": "Translate", + "summary": "Translate Text", + "description": "Translate Text", + "parameters": [ + { + "name": "X-ClientTraceId", + "in": "header", + "description": "A client-generated GUID to uniquely identify the request.", + "required": false, + "type": "string", + "x-ms-client-name": "clientTraceId" + }, + { + "name": "api-version", + "in": "query", + "description": "Mandatory API version parameter", + "required": true, + "type": "string", + "x-ms-client-name": "apiVersion" + }, + { + "name": "body", + "in": "body", + "description": "Defines the content of the request", + "required": true, + "schema": { + "$ref": "#/definitions/TranslateBody" + } + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "schema": { + "$ref": "#/definitions/TranslationResult" + }, + "headers": { + "X-RequestId": { + "type": "string", + "description": "Value generated by the service to identify the request. It is used for troubleshooting purposes." + }, + "x-metered-usage": { + "type": "integer", + "format": "int32", + "description": "Specifies consumption (the number of characters for which the user will be charged) for the translation \njob request. For example, if the word \"Hello\" is translated from English (en) to French (fr), \nthis field will return the value '5'." + }, + "x-mt-system": { + "type": "string", + "description": "Specifies the system type that was used for translation for each 'to' language requested for translation. \nThe value is a comma-separated list of strings. Each string indicates a type:\n\n* Custom - Request includes a custom system and at least one custom system was used during translation.\n* Team - All other requests" + } + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "headers": { + "X-RequestId": { + "type": "string", + "description": "Value generated by the service to identify the request. It is used for troubleshooting purposes." + } + } + } + }, + "x-ms-examples": { + "Translate Text": { + "$ref": "./examples/Translate_MaximumSet_Gen.json" + }, + "Translate Text with minimum properties": { + "$ref": "./examples/Translate_MinimumSet_Gen.json" + } + } + } + }, + "/transliterate": { + "post": { + "operationId": "Transliterate", + "summary": "Transliterate Text", + "description": "Transliterate Text", + "parameters": [ + { + "name": "X-ClientTraceId", + "in": "header", + "description": "A client-generated GUID to uniquely identify the request.", + "required": false, + "type": "string", + "x-ms-client-name": "clientTraceId" + }, + { + "$ref": "#/parameters/TransliterateParameters.language" + }, + { + "$ref": "#/parameters/TransliterateParameters.fromScript" + }, + { + "$ref": "#/parameters/TransliterateParameters.toScript" + }, + { + "name": "api-version", + "in": "query", + "description": "Mandatory API version parameter", + "required": true, + "type": "string", + "x-ms-client-name": "apiVersion" + }, + { + "name": "body", + "in": "body", + "description": "Defines the content of the request", + "required": true, + "schema": { + "$ref": "#/definitions/TransliterateBody" + } + } + ], + "responses": { + "200": { + "description": "The request has succeeded.", + "schema": { + "$ref": "#/definitions/TransliterateResult" + }, + "headers": { + "X-RequestId": { + "type": "string", + "description": "Value generated by the service to identify the request. It is used for troubleshooting purposes." + } + } + }, + "default": { + "description": "An unexpected error response.", + "schema": { + "$ref": "#/definitions/ErrorResponse" + }, + "headers": { + "X-RequestId": { + "type": "string", + "description": "Value generated by the service to identify the request. It is used for troubleshooting purposes." + } + } + } + }, + "x-ms-examples": { + "Transliterate Text": { + "$ref": "./examples/Transliterate_MaximumSet_Gen.json" + }, + "Transliterate Text with minimum properties": { + "$ref": "./examples/Transliterate_MinimumSet_Gen.json" + } + } + } + } + }, + "definitions": { + "DetectedLanguage": { + "type": "object", + "description": "An object describing the detected language.", + "properties": { + "language": { + "type": "string", + "description": "A string representing the code of the detected language." + }, + "score": { + "type": "number", + "format": "float", + "description": "A float value indicating the confidence in the result.\nThe score is between zero and one and a low score indicates a low confidence." + } + }, + "required": [ + "language", + "score" + ] + }, + "ErrorDetails": { + "type": "object", + "description": "Error details as returned by Translator Service.", + "properties": { + "code": { + "type": "string", + "description": "String identifier of the error." + }, + "message": { + "type": "string", + "description": "Human readable error description." + } + }, + "required": [ + "code", + "message" + ] + }, + "ErrorResponse": { + "type": "object", + "description": "Representation of the Error Response from Translator Service.", + "properties": { + "error": { + "$ref": "#/definitions/ErrorDetails", + "description": "Error details." + } + }, + "required": [ + "error" + ] + }, + "GetSupportedLanguagesResult": { + "type": "object", + "description": "Response for the languages API.", + "properties": { + "translation": { + "type": "object", + "description": "Languages that support translate API.", + "additionalProperties": { + "$ref": "#/definitions/TranslationLanguage" + } + }, + "transliteration": { + "type": "object", + "description": "Languages that support transliteration API.", + "additionalProperties": { + "$ref": "#/definitions/TransliterationLanguage" + } + }, + "dictionary": { + "type": "object", + "description": "Languages that support dictionary API.", + "additionalProperties": { + "$ref": "#/definitions/SourceDictionaryLanguage" + } + } + } + }, + "InputTextItem": { + "type": "object", + "description": "Element containing the text for translation.", + "properties": { + "text": { + "type": "string", + "description": "Text to translate." + } + }, + "required": [ + "text" + ] + }, + "LanguageDirectionality": { + "type": "string", + "description": "Language Directionality", + "enum": [ + "ltr", + "rtl" + ], + "x-ms-enum": { + "name": "LanguageDirectionality", + "modelAsString": false, + "values": [ + { + "name": "LeftToRight", + "value": "ltr", + "description": "Language is written left to right." + }, + { + "name": "RightToLeft", + "value": "rtl", + "description": "Language is written right to left." + } + ] + } + }, + "LanguageScript": { + "type": "object", + "description": "Common properties of language script", + "properties": { + "code": { + "type": "string", + "description": "Code identifying the script." + }, + "name": { + "type": "string", + "description": "Display name of the script in the locale requested via Accept-Language header." + }, + "nativeName": { + "type": "string", + "description": "Display name of the language in the locale native for the language." + }, + "dir": { + "$ref": "#/definitions/LanguageDirectionality", + "description": "Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages." + } + }, + "required": [ + "code", + "name", + "nativeName", + "dir" + ] + }, + "ProfanityAction": { + "type": "string", + "description": "Translator profanity actions", + "enum": [ + "NoAction", + "Marked", + "Deleted" + ], + "x-ms-enum": { + "name": "ProfanityAction", + "modelAsString": false, + "values": [ + { + "name": "NoAction", + "value": "NoAction", + "description": "No Action is taken on profanity" + }, + { + "name": "Marked", + "value": "Marked", + "description": "Profanity is marked." + }, + { + "name": "Deleted", + "value": "Deleted", + "description": "Profanity is deleted from the translated text." + } + ] + } + }, + "ProfanityMarker": { + "type": "string", + "description": "Translator profanity markers", + "enum": [ + "Asterisk", + "Tag" + ], + "x-ms-enum": { + "name": "ProfanityMarker", + "modelAsString": false, + "values": [ + { + "name": "Asterisk", + "value": "Asterisk", + "description": "Profanity is marked with asterisk." + }, + { + "name": "Tag", + "value": "Tag", + "description": "Profanity is marked with the tags." + } + ] + } + }, + "ReferenceSentencePair": { + "type": "object", + "description": "Reference sentence pair.", + "properties": { + "source": { + "type": "string", + "description": "Source reference sentence." + }, + "target": { + "type": "string", + "description": "Target reference sentence." + } + }, + "required": [ + "source", + "target" + ] + }, + "SourceDictionaryLanguage": { + "type": "object", + "description": "Properties ot the source dictionary language", + "properties": { + "name": { + "type": "string", + "description": "Display name of the language in the locale requested via Accept-Language header." + }, + "nativeName": { + "type": "string", + "description": "Display name of the language in the locale native for this language." + }, + "dir": { + "$ref": "#/definitions/LanguageDirectionality", + "description": "Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages." + }, + "translations": { + "type": "array", + "description": "List of languages with alterative translations and examples for the query expressed in the source language.", + "items": { + "$ref": "#/definitions/TargetDictionaryLanguage" + } + } + }, + "required": [ + "name", + "nativeName", + "dir", + "translations" + ] + }, + "TargetDictionaryLanguage": { + "type": "object", + "description": "Properties of the target dictionary language", + "properties": { + "name": { + "type": "string", + "description": "Display name of the language in the locale requested via Accept-Language header." + }, + "nativeName": { + "type": "string", + "description": "Display name of the language in the locale native for this language." + }, + "dir": { + "$ref": "#/definitions/LanguageDirectionality", + "description": "Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages." + }, + "code": { + "type": "string", + "description": "Language code identifying the target language." + } + }, + "required": [ + "name", + "nativeName", + "dir", + "code" + ] + }, + "TextType": { + "type": "string", + "description": "Translation text type", + "enum": [ + "Plain", + "Html" + ], + "x-ms-enum": { + "name": "TextType", + "modelAsString": true, + "values": [ + { + "name": "Plain", + "value": "Plain", + "description": "Plain text." + }, + { + "name": "Html", + "value": "Html", + "description": "HTML-encoded text." + } + ] + } + }, + "TranslateBody": { + "type": "object", + "description": "Request body for the translate API.", + "properties": { + "inputs": { + "type": "array", + "description": "Array of the input text elements to translate.", + "items": { + "$ref": "#/definitions/TranslateInputItem" + } + } + }, + "required": [ + "inputs" + ] + }, + "TranslateInputItem": { + "type": "object", + "description": "Element containing the text for translation.", + "properties": { + "text": { + "type": "string", + "description": "Text to translate." + }, + "script": { + "type": "string", + "description": "Specifies the script of the input text." + }, + "language": { + "type": "string", + "description": "Specifies the language of the input text. Find which languages are available to translate by \nlooking up supported languages using the translation scope. If the language parameter isn't \nspecified, automatic language detection is applied to determine the source language.\n\nYou must use the language parameter rather than autodetection when using the dynamic dictionary feature. \nNote: the dynamic dictionary feature is case-sensitive." + }, + "textType": { + "type": "string", + "description": "Defines whether the text being translated is plain text or HTML text. Any HTML needs to be a well-formed, \ncomplete element. Possible values are: plain (default) or html.", + "default": "Plain", + "enum": [ + "Plain", + "Html" + ], + "x-ms-enum": { + "name": "TextType", + "modelAsString": true, + "values": [ + { + "name": "Plain", + "value": "Plain", + "description": "Plain text." + }, + { + "name": "Html", + "value": "Html", + "description": "HTML-encoded text." + } + ] + } + }, + "targets": { + "type": "array", + "description": "Translation target parameters.", + "items": { + "$ref": "#/definitions/TranslateTarget" + } + } + }, + "required": [ + "text", + "targets" + ] + }, + "TranslateParameters": { + "type": "object", + "description": "Request parameters for the translate API." + }, + "TranslateTarget": { + "type": "object", + "description": "Translate targets parameters", + "properties": { + "language": { + "type": "string", + "description": "Specifies the language of the output text. The target language must be one of the supported languages included \nin the translation scope. It's possible to translate to multiple languages simultaneously by including \nmultiple string values in the targetsLanguage array." + }, + "script": { + "type": "string", + "description": "Specifies the script of the translated text." + }, + "profanityAction": { + "type": "string", + "description": "Specifies how profanities should be treated in translations.\nPossible values are: NoAction (default), Marked or Deleted.", + "default": "NoAction", + "enum": [ + "NoAction", + "Marked", + "Deleted" + ], + "x-ms-enum": { + "name": "ProfanityAction", + "modelAsString": false, + "values": [ + { + "name": "NoAction", + "value": "NoAction", + "description": "No Action is taken on profanity" + }, + { + "name": "Marked", + "value": "Marked", + "description": "Profanity is marked." + }, + { + "name": "Deleted", + "value": "Deleted", + "description": "Profanity is deleted from the translated text." + } + ] + } + }, + "profanityMarker": { + "type": "string", + "description": "Specifies how profanities should be marked in translations.\nPossible values are: Asterisk (default) or Tag. ", + "default": "Asterisk", + "enum": [ + "Asterisk", + "Tag" + ], + "x-ms-enum": { + "name": "ProfanityMarker", + "modelAsString": false, + "values": [ + { + "name": "Asterisk", + "value": "Asterisk", + "description": "Profanity is marked with asterisk." + }, + { + "name": "Tag", + "value": "Tag", + "description": "Profanity is marked with the tags." + } + ] + } + }, + "deploymentName": { + "type": "string", + "description": "Default is ‘general’, which uses NMT system.\n‘abc-inc-gpt-4o’, and ‘abc-inc-gpt-4o-mini’ are examples of deployment names which use GPT-4o uses or \nGPT-4o-mini model. ‘gpt-4o’ uses GPT-4o model. \n\n‘’ uses the custom NMT model tuned by customer.\n‘best’ system determines which is the best model to use for the request. This intelligence could be introduced\nin future. Customer should have deployed it in their resource.\n", + "default": "general" + }, + "allowFallback": { + "type": "boolean", + "description": "In the case where a custom system is being used, specifies that the service is allowed to fall back to a\ngeneral system when a custom system doesn't exist. \nIn the case where a Large Language Model is being used, specifies that the service is allowed to fall\nback to a Small Language Model if an error occurs.\nPossible values are: true (default) or false.\n\nallowFallback=false specifies that the translation should only use systems trained for the category specified \nby the request. If a translation for language X to language Y requires chaining through a pivot language E, \nthen all the systems in the chain (X → E and E → Y) will need to be custom and have the same category. \nIf no system is found with the specific category, the request will return a 400 status code. allowFallback=true \nspecifies that the service is allowed to fall back to a general system when a custom system doesn't exist.", + "default": true + }, + "grade": { + "type": "string", + "description": "Defines complexity of LLM prompts to provide high accuracy translation.", + "default": "basic" + }, + "tone": { + "type": "string", + "description": "Desired tone of target translation." + }, + "gender": { + "type": "string", + "description": "Desired gender of target translation." + }, + "adaptiveDatasetId": { + "type": "string", + "description": "Reference dataset ID having sentence pair to generate adaptive customized translation." + }, + "referenceTextPairs": { + "type": "array", + "description": "Reference sentence pairs to generate adaptive results.", + "maxItems": 5, + "items": { + "$ref": "#/definitions/ReferenceSentencePair" + } + } + }, + "required": [ + "language" + ] + }, + "TranslatedTextItem": { + "type": "object", + "description": "Element containing the translated text", + "properties": { + "detectedLanguage": { + "$ref": "#/definitions/DetectedLanguage", + "description": "The detectedLanguage property is only present in the result object when language auto-detection is requested." + }, + "translations": { + "type": "array", + "description": "An array of translation results. The size of the array matches the number of target \nlanguages specified through the to query parameter.", + "items": { + "$ref": "#/definitions/TranslationText" + } + } + }, + "required": [ + "translations" + ] + }, + "TranslationLanguage": { + "type": "object", + "description": "The value of the translation property is a dictionary of (key, value) pairs. Each key is a BCP 47 language tag.\nA key identifies a language for which text can be translated to or translated from.", + "properties": { + "name": { + "type": "string", + "description": "Display name of the language in the locale requested via Accept-Language header." + }, + "nativeName": { + "type": "string", + "description": "Display name of the language in the locale native for this language." + }, + "dir": { + "$ref": "#/definitions/LanguageDirectionality", + "description": "Directionality, which is rtl for right-to-left languages or ltr for left-to-right languages." + } + }, + "required": [ + "name", + "nativeName", + "dir" + ] + }, + "TranslationResult": { + "type": "object", + "description": "Response for the translation API.", + "properties": { + "value": { + "type": "array", + "description": "Array of the translated text elements.", + "items": { + "$ref": "#/definitions/TranslatedTextItem" + } + } + }, + "required": [ + "value" + ] + }, + "TranslationText": { + "type": "object", + "description": "Translation result", + "properties": { + "language": { + "type": "string", + "description": "A string representing the language code of the target language." + }, + "sourceCharacters": { + "type": "integer", + "format": "int32", + "description": "An interger indicating the number of characters in the source text string" + }, + "instructionTokens": { + "type": "integer", + "format": "int32", + "description": "An interger indicating the number of tokens used in generating the translated text" + }, + "sourceTokens": { + "type": "integer", + "format": "int32", + "description": "An interger indicating the number of tokens used in the source sentence" + }, + "responseTokens": { + "type": "integer", + "format": "int32", + "description": "An interger indicating the number of tokens used in the translation response" + }, + "targetTokens": { + "type": "integer", + "format": "int32", + "description": "An interger indicating the number of tokens used in the target sentence" + }, + "text": { + "type": "string", + "description": "A string giving the translated text." + } + }, + "required": [ + "language", + "text" + ] + }, + "TransliterableScript": { + "type": "object", + "description": "Script definition with list of script into which given script can be translitered.", + "properties": { + "toScripts": { + "type": "array", + "description": "List of scripts available to convert text to.", + "items": { + "$ref": "#/definitions/LanguageScript" + } + } + }, + "required": [ + "toScripts" + ], + "allOf": [ + { + "$ref": "#/definitions/LanguageScript" + } + ] + }, + "TransliterateBody": { + "type": "object", + "description": "Request body for the transliterate API.", + "properties": { + "inputs": { + "type": "array", + "description": "Array of the input text elements to transliterate.", + "items": { + "$ref": "#/definitions/InputTextItem" + } + } + }, + "required": [ + "inputs" + ] + }, + "TransliterateResult": { + "type": "object", + "description": "Response for the transliteration API.", + "properties": { + "value": { + "type": "array", + "description": "Array of transliterated texts", + "items": { + "$ref": "#/definitions/TransliteratedText" + } + } + }, + "required": [ + "value" + ] + }, + "TransliteratedText": { + "type": "object", + "description": "Transliterated text element.", + "properties": { + "text": { + "type": "string", + "description": "A string which is the result of converting the input string to the output script." + }, + "script": { + "type": "string", + "description": "A string specifying the script used in the output." + } + }, + "required": [ + "text", + "script" + ] + }, + "TransliterationLanguage": { + "type": "object", + "description": "The value of the transliteration property is a dictionary of (key, value) pairs. \nEach key is a BCP 47 language tag. A key identifies a language for which text can be converted from one script \nto another script.", + "properties": { + "name": { + "type": "string", + "description": "Display name of the language in the locale requested via Accept-Language header." + }, + "nativeName": { + "type": "string", + "description": "Display name of the language in the locale native for this language." + }, + "scripts": { + "type": "array", + "description": "List of scripts to convert from.", + "items": { + "$ref": "#/definitions/TransliterableScript" + } + } + }, + "required": [ + "name", + "nativeName", + "scripts" + ] + } + }, + "parameters": { + "GetSupportedLanguagesParameters.acceptLanguage": { + "name": "Accept-Language", + "in": "header", + "description": "The language to use for user interface strings. Some of the fields in the response are names of languages or \nnames of regions. Use this parameter to define the language in which these names are returned. \nThe language is specified by providing a well-formed BCP 47 language tag. For instance, use the value `fr` \nto request names in French or use the value `zh-Hant` to request names in Chinese Traditional.\nNames are provided in the English language when a target language is not specified or when localization \nis not available.", + "required": false, + "type": "string", + "default": "en", + "x-ms-parameter-location": "method", + "x-ms-client-name": "acceptLanguage" + }, + "GetSupportedLanguagesParameters.ifNoneMatch": { + "name": "If-None-Match", + "in": "header", + "description": "Passing the value of the ETag response header in an If-None-Match field will allow the service to optimize the response. \nIf the resource has not been modified, the service will return status code 304 and an empty response body.", + "required": false, + "type": "string", + "x-ms-parameter-location": "method", + "x-ms-client-name": "ifNoneMatch" + }, + "GetSupportedLanguagesParameters.scope": { + "name": "scope", + "in": "query", + "description": "A comma-separated list of names defining the group of languages to return.\nAllowed group names are: `translation`, `transliteration` and `dictionary`.\nIf no scope is given, then all groups are returned, which is equivalent to passing \n`scope=translation,transliteration,dictionary`. To decide which set of supported languages \nis appropriate for your scenario, see the description of the [response object](#response-body).", + "required": false, + "type": "string", + "x-ms-parameter-location": "method" + }, + "TransliterateParameters.fromScript": { + "name": "fromScript", + "in": "query", + "description": "Specifies the script used by the input text. Look up supported languages using the transliteration scope,\nto find input scripts available for the selected language.", + "required": true, + "type": "string", + "x-ms-parameter-location": "method" + }, + "TransliterateParameters.language": { + "name": "language", + "in": "query", + "description": "Specifies the language of the text to convert from one script to another. \nPossible languages are listed in the transliteration scope obtained by querying the service \nfor its supported languages.", + "required": true, + "type": "string", + "x-ms-parameter-location": "method" + }, + "TransliterateParameters.toScript": { + "name": "toScript", + "in": "query", + "description": "Specifies the output script. Look up supported languages using the transliteration scope, to find output \nscripts available for the selected combination of input language and input script.", + "required": true, + "type": "string", + "x-ms-parameter-location": "method" + } + } +} diff --git a/specification/translation/data-plane/TextTranslation/readme.md b/specification/translation/data-plane/TextTranslation/readme.md index a68c2941053c..020bae8a2c56 100644 --- a/specification/translation/data-plane/TextTranslation/readme.md +++ b/specification/translation/data-plane/TextTranslation/readme.md @@ -2,26 +2,44 @@ > see https://aka.ms/autorest -Configuration for generating Translation Text SDK. +This is the AutoRest configuration file for Translation Text SDK. -The current release is `release_3_0`. +> `autorest` + +To see additional help and options, run: + +> `autorest --help` +--- + +The current release is `package-2025-10-01-preview`. ``` yaml -tag: release_3_0 +tag: package-2025-10-01-preview add-credentials: true openapi-type: data-plane ``` -# Releases +## Releases ### Release 3.0 + These settings apply only when `--tag=release_3_0` is specified on the command line. ``` yaml $(tag) == 'release_3_0' input-file: stable/3.0/openapi.json ``` -## Multi-API/Profile support for AutoRest v3 generators +### Release 2025-10-01-preview + +These settings apply only when `--tag=package-2025-10-01-preview` is specified on the command line. + +``` yaml $(tag) == 'package-2025-10-01-preview' +version: package-2025-10-01-preview +input-file: + - preview/2025-10-01-preview/openapi.json +``` + +## Multi-API/Profile support for AutoRest v3 generators AutoRest V3 generators require the use of `--tag=all-api-versions` to select api files. @@ -34,12 +52,13 @@ require: $(this-folder)/../../../../profiles/readme.md # all the input files across all versions input-file: - $(this-folder)/stable/3.0/openapi.json + - $(this-folder)/preview/2025-10-01-preview/openapi.json ``` -If there are files that should not be in the `all-api-versions` set, +If there are files that should not be in the `all-api-versions` set, uncomment the `exclude-file` section below and add the file paths. ``` yaml $(tag) == 'all-api-versions' #exclude-file: # - $(this-folder)/Microsoft.Example/stable/2010-01-01/somefile.json -``` +``` \ No newline at end of file diff --git a/specification/translation/data-plane/TextTranslation/routes.tsp b/specification/translation/data-plane/TextTranslation/routes.tsp index a59a25aa2362..f677d46cb80a 100644 --- a/specification/translation/data-plane/TextTranslation/routes.tsp +++ b/specification/translation/data-plane/TextTranslation/routes.tsp @@ -1,25 +1,20 @@ import "@typespec/rest"; import "@azure-tools/typespec-azure-core"; +import "@azure-tools/typespec-client-generator-core"; import "./models-languages.tsp"; import "./models-translate.tsp"; import "./models-transliterate.tsp"; import "./models-breaksentence.tsp"; import "./models-dictionary.tsp"; -using Azure.Core; -using TypeSpec.Rest; +using Azure.ClientGenerator.Core; using TypeSpec.Http; +using TypeSpec.Versioning; namespace TextTranslation; @doc("Defines Text Translation custom Operation") -op CustomOperation< - TBody, - TParams, - TResponse, - Traits = {}, - TError = ErrorResponse ->( +op CustomOperation( ...TParams, #suppress "@azure-tools/typespec-azure-core/request-body-problem" "Existing spec" @@ -33,7 +28,7 @@ op CustomOperation< ): TResponse | TError; @doc("Defines Text Translation custom Operations which doesn't have any content in the request") -op CustomGetOperation( +op CustomGetOperation( ...TParams, @doc("Mandatory API version parameter") @@ -49,37 +44,69 @@ op CustomGetOperation( op getSupportedLanguages is CustomGetOperation< GetSupportedLanguagesParameters, GetSupportedLanguagesResult, - {}, ErrorResponse >; #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "This is an existing service, we have a non-conforming operation." @post +@summary("Translate Text") +@doc("Translate Text") @route("translate") +@sharedRoute +@renamedFrom(APIVersion.v2025_10_01_preview, "translate") +@removed(APIVersion.v2025_10_01_preview) +op translateV3 is CustomOperation< + InputTextItem[], + TranslateParameters, + TranslationResultV3, + ErrorResponse +>; + +#suppress "@azure-tools/typespec-azure-core/use-standard-operations" "This is an existing service, we have a non-conforming operation." +@post +@sharedRoute @summary("Translate Text") @doc("Translate Text") +@route("translate") +@added(APIVersion.v2025_10_01_preview) op translate is CustomOperation< - InputTextItem[], + TranslateBody, TranslateParameters, TranslationResult, - {}, ErrorResponse >; #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "This is an existing service, we have a non-conforming operation." @post +@sharedRoute @route("transliterate") @summary("Transliterate Text") @doc("Transliterate Text") -op transliterate is CustomOperation< +@renamedFrom(APIVersion.v2025_10_01_preview, "transliterate") +@removed(APIVersion.v2025_10_01_preview) +op transliterateV3 is CustomOperation< InputTextItem[], TransliterateParameters, + TransliterateResultV3, + ErrorResponse +>; + +#suppress "@azure-tools/typespec-azure-core/use-standard-operations" "This is an existing service, we have a non-conforming operation." +@post +@sharedRoute +@route("transliterate") +@summary("Transliterate Text") +@doc("Transliterate Text") +@added(APIVersion.v2025_10_01_preview) +op transliterate is CustomOperation< + TransliterateBody, + TransliterateParameters, TransliterateResult, - {}, ErrorResponse >; #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "This is an existing service, we have a non-conforming operation." +@removed(APIVersion.v2025_10_01_preview) @post @route("breaksentence") @summary("Find Sentence Boundaries") @@ -88,11 +115,11 @@ op findSentenceBoundaries is CustomOperation< InputTextItem[], BreakSentenceParameters, BreakSentenceResult, - {}, ErrorResponse >; #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "This is an existing service, we have a non-conforming operation." +@removed(APIVersion.v2025_10_01_preview) @post @route("dictionary/lookup") @summary("Lookup Dictionary Entries") @@ -101,7 +128,6 @@ op lookupDictionaryEntries is CustomOperation< InputTextItem[], DictionaryLookupParameters, DictionaryLookupResult, - {}, ErrorResponse >; @@ -110,10 +136,10 @@ op lookupDictionaryEntries is CustomOperation< @route("dictionary/examples") @summary("Lookup Dictionary Examples") @doc("Lookup Dictionary Examples") +@removed(APIVersion.v2025_10_01_preview) op lookupDictionaryExamples is CustomOperation< DictionaryExampleTextItem[], DictionaryExamplesParameters, DictionaryExamplesResult, - {}, ErrorResponse >; diff --git a/specification/translation/data-plane/TextTranslation/stable/3.0/openapi.json b/specification/translation/data-plane/TextTranslation/stable/3.0/openapi.json index 888c310b8533..8f53bc59db5b 100644 --- a/specification/translation/data-plane/TextTranslation/stable/3.0/openapi.json +++ b/specification/translation/data-plane/TextTranslation/stable/3.0/openapi.json @@ -3,7 +3,7 @@ "info": { "title": "Text Translation", "version": "3.0", - "description": "Text translation is a cloud-based REST API feature of the Translator service that uses neural\nmachine translation technology to enable quick and accurate source-to-target text translation\nin real time across all supported languages.\n\nThe following methods are supported by the Text Translation feature:\n\nLanguages. Returns a list of languages supported by Translate, Transliterate, and Dictionary Lookup operations.\n\nTranslate. Renders single source-language text to multiple target-language texts with a single request.\n\nTransliterate. Converts characters or letters of a source language to the corresponding characters or letters of a target language.\n\nDetect. Returns the source code language code and a boolean variable denoting whether the detected language is supported for text translation and transliteration.\n\nDictionary lookup. Returns equivalent words for the source term in the target language.\n\nDictionary example Returns grammatical structure and context examples for the source term and target term pair.", + "description": "Text translation is a cloud-based REST API feature of the Translator service that uses neural\nmachine translation technology to enable quick and accurate source-to-target text translation\nin real time across all supported languages.\n\nThe following methods are supported by the Text Translation feature:\n\nLanguages. Returns a list of languages supported by Translate, Transliterate, and Dictionary Lookup operations.\n\nTranslate. Renders single source-language text to multiple target-language texts with a single request.\n\nTransliterate. Converts characters or letters of a source language to the corresponding characters or letters of a target language.\n\nDetect. Returns the source code language code and a boolean variable denoting whether the detected language is supported for text translation and transliteration.", "x-typespec-generated": [ { "emitter": "@azure-tools/typespec-autorest"