[translation] arch feedback

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

@@ -2,13 +2,15 @@
 
 ## 1.0.0 (Unreleased)
 
-### Features Added
-
 ### Breaking Changes
 
-### Bugs Fixed
+- Changed: `begin_translation` parameter `target_language_code` has been renamed to `target_language`.
+- Changed: `begin_translation` keyword-only argument `source_language_code` has been renamed to `source_language`.
+- Changed: `DocumentTranslationInput` keyword-only argument and property `source_language_code` has been renamed to `source_language`.
+- Changed: `TranslationTarget` keyword-only argument and property `language_code` has been renamed to `language`.
+- Changed: `TranslationStatus` property `documents_not_yet_started_count` has been renamed to `documents_not_started_count`.
+- Removed: `results_per_page` keyword-only argument from `list_translation_statuses` and `list_document_statuses`.
 
-### Other Changes
 
 ## 1.0.0b6 (2022-02-08)
 

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

@@ -150,7 +150,7 @@ from azure.core.credentials import AzureKeyCredential
 from azure.ai.translation.document import DocumentTranslationClient
 
 document_translation_client = DocumentTranslationClient("<endpoint>", AzureKeyCredential("<api_key>"))
-poller = document_translation_client.begin_translation("<sas_url_to_source>", "<sas_url_to_target>", "<target_language_code>")
+poller = document_translation_client.begin_translation("<sas_url_to_source>", "<sas_url_to_target>", "<target_language>")
 ```
 
 2) Or multiple different sources can be provided each with their own targets.
@@ -163,22 +163,22 @@ my_input = [
     DocumentTranslationInput(
         source_url="<sas_url_to_source_A>",
         targets=[
-            TranslationTarget(target_url="<sas_url_to_target_fr>", language_code="fr"),
-            TranslationTarget(target_url="<sas_url_to_target_de>", language_code="de")
+            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
+            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
         ]
     ),
     DocumentTranslationInput(
         source_url="<sas_url_to_source_B>",
         targets=[
-            TranslationTarget(target_url="<sas_url_to_target_fr>", language_code="fr"),
-            TranslationTarget(target_url="<sas_url_to_target_de>", language_code="de")
+            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
+            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
         ]
     ),
     DocumentTranslationInput(
         source_url="<sas_url_to_source_C>",
         targets=[
-            TranslationTarget(target_url="<sas_url_to_target_fr>", language_code="fr"),
-            TranslationTarget(target_url="<sas_url_to_target_de>", language_code="de")
+            TranslationTarget(target_url="<sas_url_to_target_fr>", language="fr"),
+            TranslationTarget(target_url="<sas_url_to_target_de>", language="de")
         ]
     )
 ]
@@ -270,14 +270,14 @@ poller = document_translation_client.begin_translation(
         DocumentTranslationInput(
             source_url=source_container_sas_url_en,
             targets=[
-                TranslationTarget(target_url=target_container_sas_url_es, language_code="es"),
-                TranslationTarget(target_url=target_container_sas_url_fr, language_code="fr"),
+                TranslationTarget(target_url=target_container_sas_url_es, language="es"),
+                TranslationTarget(target_url=target_container_sas_url_fr, language="fr"),
             ],
         ),
         DocumentTranslationInput(
             source_url=source_container_sas_url_de,
             targets=[
-                TranslationTarget(target_url=target_container_sas_url_ar, language_code="ar"),
+                TranslationTarget(target_url=target_container_sas_url_ar, language="ar"),
             ],
         )
     ]

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

@@ -110,9 +110,9 @@ def begin_translation(
         self,
         source_url: str,
         target_url: str,
-        target_language_code: str,
+        target_language: str,
         *,
-        source_language_code: Optional[str] = None,
+        source_language: Optional[str] = None,
         prefix: Optional[str] = None,
         suffix: Optional[str] = None,
         storage_type: Optional[Union[str, StorageInputType]] = None,
@@ -124,7 +124,7 @@ def begin_translation(
         in the given language. There are two ways to call this method:
 
         1) To perform translation on documents from a single source container to a single target container, pass the
-        `source_url`, `target_url`, and `target_language_code` parameters including any optional keyword arguments.
+        `source_url`, `target_url`, and `target_language` parameters including any optional keyword arguments.
 
         2) To pass multiple inputs for translation (multiple sources or targets), pass the `inputs` parameter
         as a list of :class:`~azure.ai.translation.document.DocumentTranslationInput`.
@@ -138,10 +138,10 @@ def begin_translation(
         :param str target_url: The target SAS URL to the Azure Blob container where the translated documents
             should be written. See the service documentation for the supported SAS permissions for accessing
             target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
-        :param str target_language_code: This is the language you want your documents to be translated to.
+        :param str target_language: This is the language code you want your documents to be translated to.
             See supported language codes here:
             https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate
-        :keyword str source_language_code: Language code for the source documents.
+        :keyword str source_language: 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
@@ -169,7 +169,7 @@ def begin_translation(
         in the given language. There are two ways to call this method:
 
         1) To perform translation on documents from a single source container to a single target container, pass the
-        `source_url`, `target_url`, and `target_language_code` parameters including any optional keyword arguments.
+        `source_url`, `target_url`, and `target_language` parameters including any optional keyword arguments.
 
         2) To pass multiple inputs for translation (multiple sources or targets), pass the `inputs` parameter
         as a list of :class:`~azure.ai.translation.document.DocumentTranslationInput`.
@@ -196,7 +196,7 @@ def begin_translation(
         in the given language. There are two ways to call this method:
 
         1) To perform translation on documents from a single source container to a single target container, pass the
-        `source_url`, `target_url`, and `target_language_code` parameters including any optional keyword arguments.
+        `source_url`, `target_url`, and `target_language` parameters including any optional keyword arguments.
 
         2) To pass multiple inputs for translation (multiple sources or targets), pass the `inputs` parameter
         as a list of :class:`~azure.ai.translation.document.DocumentTranslationInput`.
@@ -214,14 +214,14 @@ def begin_translation(
             for accessing target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions)
             or a managed identity can be created and used to access documents in your storage account
             (see https://aka.ms/azsdk/documenttranslation/managed-identity).
-        :param str target_language_code: This is the language you want your documents to be translated to.
+        :param str target_language: This is the language code you want your documents to be translated to.
             See supported language codes here:
             https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate
         :param inputs: A list of translation inputs. Each individual input has a single
             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.
+        :keyword str source_language: 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
@@ -330,7 +330,6 @@ def list_translation_statuses(
         *,
         top: Optional[int] = None,
         skip: Optional[int] = None,
-        results_per_page: Optional[int] = None,
         translation_ids: Optional[List[str]] = None,
         statuses: Optional[List[str]] = None,
         created_after: Optional[Union[str, datetime.datetime]] = None,
@@ -343,7 +342,6 @@ def list_translation_statuses(
         :keyword int top: the total number of operations to return (across all pages) from all submitted translations.
         :keyword int skip: the number of operations to skip (from beginning of all submitted operations).
             By default, we sort by all submitted operations in descending order by start time.
-        :keyword int results_per_page: is the number of operations returned per page.
         :keyword list[str] translation_ids: translation operations ids to filter by.
         :keyword list[str] statuses: translation operation statuses to filter by. Options include
             'NotStarted', 'Running', 'Succeeded', 'Failed', 'Canceled', 'Canceling',
@@ -393,7 +391,6 @@ def _convert_from_generated_model(
         return cast(ItemPaged[TranslationStatus],
             self._client.document_translation.get_translations_status(
                 cls=model_conversion_function,
-                maxpagesize=results_per_page,
                 created_date_time_utc_start=created_after,
                 created_date_time_utc_end=created_before,
                 ids=translation_ids,
@@ -412,7 +409,6 @@ def list_document_statuses(
         *,
         top: Optional[int] = None,
         skip: Optional[int] = None,
-        results_per_page: Optional[int] = None,
         document_ids: Optional[List[str]] = None,
         statuses: Optional[List[str]] = None,
         created_after: Optional[Union[str, datetime.datetime]] = None,
@@ -426,7 +422,6 @@ def list_document_statuses(
         :keyword int top: the total number of documents to return (across all pages).
         :keyword int skip: the number of documents to skip (from beginning).
             By default, we sort by all documents in descending order by start time.
-        :keyword int results_per_page: is the number of documents returned per page.
         :keyword list[str] document_ids: document IDs to filter by.
         :keyword list[str] statuses: document statuses to filter by. Options include
             'NotStarted', 'Running', 'Succeeded', 'Failed', 'Canceled', 'Canceling',
@@ -479,7 +474,6 @@ def _convert_from_generated_model(generated_model):
             self._client.document_translation.get_documents_status(
                 id=translation_id,
                 cls=model_conversion_function,
-                maxpagesize=results_per_page,
                 created_date_time_utc_start=created_after,
                 created_date_time_utc_end=created_before,
                 ids=document_ids,

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

@@ -40,12 +40,12 @@ def get_translation_input(args, kwargs, continuation_token):
             target_url = kwargs.pop("target_url", None)
             if not target_url:
                 target_url = args[1]
-            target_language_code = kwargs.pop("target_language_code", None)
-            if not target_language_code:
-                target_language_code = args[2]
+            target_language = kwargs.pop("target_language", None)
+            if not target_language:
+                target_language = args[2]
 
             # Additional kwargs
-            source_language_code = kwargs.pop("source_language_code", None)
+            source_language = kwargs.pop("source_language", None)
             prefix = kwargs.pop("prefix", None)
             suffix = kwargs.pop("suffix", None)
             storage_type = kwargs.pop("storage_type", None)
@@ -60,12 +60,12 @@ def get_translation_input(args, kwargs, continuation_token):
                             prefix=prefix,
                             suffix=suffix
                         ),
-                        language=source_language_code,
+                        language=source_language,
                     ),
                     targets=[
                         _TargetInput(
                             target_url=target_url,
-                            language=target_language_code,
+                            language=target_language,
                             glossaries=[g._to_generated() for g in glossaries]  # pylint: disable=protected-access
                             if glossaries else None,
                             category=category_id,
@@ -77,7 +77,7 @@ def get_translation_input(args, kwargs, continuation_token):
         except (AttributeError, TypeError, IndexError):
             raise ValueError(
                 "Pass 'inputs' for multiple inputs or 'source_url', 'target_url', "
-                "and 'target_language_code' for a single input."
+                "and 'target_language' for a single input."
             )
 
     return request