[translation] support translation kwargs for single translation overload (Azure#19851)

* support kwargs in the single overload

* add docstrings for kwargs

* pylint and changelog

* tests and fixes

* don't expose storage source kwargs for now

Author: kristapratico

sdk/translation/azure-ai-translation-document/CHANGELOG.md

@@ -4,6 +4,9 @@
 
 ### Features Added
 
+- The single translation input version of `begin_translation(source, target, target_language_code)` now accepts keyword arguments
+`storage_type`, `glossaries`, `category_id`, `prefix`, `suffix`, and `source_language_code`.
+
 ### Breaking Changes
 
 - Changed: renamed kwargs `translated_before` and `translated_after` to `created_before` and `created_after`, respectively,

sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_client.py

@@ -114,8 +114,8 @@ def begin_translation(
     ):  # pylint: disable=client-method-missing-type-annotations
         """Begin translating the document(s) in your source container to your target container
         in the given language. To perform a single translation from source to target, pass the `source_url`,
-        `target_url`, and `target_language_code` parameters. To pass multiple inputs for translation, including
-        other translation options, pass the `inputs` parameter as a list of
+        `target_url`, and `target_language_code` parameters including any optional keyword arguments.
+        To pass multiple inputs for translation, pass the `inputs` parameter as a list of
         :class:`~azure.ai.translation.document.DocumentTranslationInput`.
 
         For supported languages and document formats, see the service documentation:
@@ -132,6 +132,19 @@ def begin_translation(
             source URL to documents and can contain multiple TranslationTargets (one for each language)
             for the destination to write translated documents.
         :type inputs: List[~azure.ai.translation.document.DocumentTranslationInput]
+        :keyword str source_language_code: Language code for the source documents.
+            If none is specified, the source language will be auto-detected for each document.
+        :keyword str prefix: A case-sensitive prefix string to filter documents in the source path for
+            translation. For example, when using a Azure storage blob Uri, use the prefix to restrict
+            sub folders for translation.
+        :keyword str suffix: A case-sensitive suffix string to filter documents in the source path for
+            translation. This is most often use for file extensions.
+        :keyword storage_type: Storage type of the input documents source string. Possible values
+            include: "Folder", "File".
+        :paramtype storage_type: str or ~azure.ai.translation.document.StorageInputType
+        :keyword str category_id: Category / custom model ID for using custom translation.
+        :keyword glossaries: Glossaries to apply to translation.
+        :paramtype glossaries: list[~azure.ai.translation.document.TranslationGlossary]
         :return: An instance of a DocumentTranslationLROPoller. Call `result()` on the poller
             object to return a pageable of DocumentStatus. A DocumentStatus will be
             returned for each translation on a document.

sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_helpers.py

@@ -14,6 +14,7 @@
     BatchRequest as _BatchRequest,
     SourceInput as _SourceInput,
     TargetInput as _TargetInput,
+    DocumentFilter as _DocumentFilter,
 )
 from ._models import DocumentTranslationInput
 
@@ -44,14 +45,35 @@ def get_translation_input(args, kwargs, continuation_token):
             target_language_code = kwargs.pop("target_language_code", None)
             if not target_language_code:
                 target_language_code = args[2]
+
+            # Additional kwargs
+            source_language_code = kwargs.pop("source_language_code", None)
+            prefix = kwargs.pop("prefix", None)
+            suffix = kwargs.pop("suffix", None)
+            storage_type = kwargs.pop("storage_type", None)
+            category_id = kwargs.pop("category_id", None)
+            glossaries = kwargs.pop("glossaries", None)
+
             request = [
                 _BatchRequest(
-                    source=_SourceInput(source_url=source_url),
+                    source=_SourceInput(
+                        source_url=source_url,
+                        filter=_DocumentFilter(
+                            prefix=prefix,
+                            suffix=suffix
+                        ),
+                        language=source_language_code,
+                    ),
                     targets=[
                         _TargetInput(
-                            target_url=target_url, language=target_language_code
+                            target_url=target_url,
+                            language=target_language_code,
+                            glossaries=[g._to_generated() for g in glossaries]  # pylint: disable=protected-access
+                            if glossaries else None,
+                            category=category_id,
                         )
                     ],
+                    storage_type=storage_type
                 )
             ]
         except (AttributeError, TypeError, IndexError):

sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_client_async.py

@@ -123,8 +123,8 @@ async def begin_translation(
     ):  # pylint: disable=client-method-missing-type-annotations
         """Begin translating the document(s) in your source container to your target container
         in the given language. To perform a single translation from source to target, pass the `source_url`,
-        `target_url`, and `target_language_code` parameters. To pass multiple inputs for translation, including
-        other translation options, pass the `inputs` parameter as a list of
+        `target_url`, and `target_language_code` parameters including any optional keyword arguments.
+        To pass multiple inputs for translation, pass the `inputs` parameter as a list of
         :class:`~azure.ai.translation.document.DocumentTranslationInput`.
 
         For supported languages and document formats, see the service documentation:
@@ -141,6 +141,19 @@ async def begin_translation(
             source URL to documents and can contain multiple TranslationTargets (one for each language)
             for the destination to write translated documents.
         :type inputs: List[~azure.ai.translation.document.DocumentTranslationInput]
+        :keyword str source_language_code: Language code for the source documents.
+            If none is specified, the source language will be auto-detected for each document.
+        :keyword str prefix: A case-sensitive prefix string to filter documents in the source path for
+            translation. For example, when using a Azure storage blob Uri, use the prefix to restrict
+            sub folders for translation.
+        :keyword str suffix: A case-sensitive suffix string to filter documents in the source path for
+            translation. This is most often use for file extensions.
+        :keyword storage_type: Storage type of the input documents source string. Possible values
+            include: "Folder", "File".
+        :paramtype storage_type: str or ~azure.ai.translation.document.StorageInputType
+        :keyword str category_id: Category / custom model ID for using custom translation.
+        :keyword glossaries: Glossaries to apply to translation.
+        :paramtype glossaries: list[~azure.ai.translation.document.TranslationGlossary]
         :return: An instance of an AsyncDocumentTranslationLROPoller. Call `result()` on the poller
             object to return a pageable of DocumentStatus. A DocumentStatus will be
             returned for each translation on a document.