Skip to content
This repository has been archived by the owner on Mar 6, 2023. It is now read-only.

Commit

Permalink
Fixed spelling mistakes in the migration guide
Browse files Browse the repository at this point in the history
  • Loading branch information
lecode-official committed Nov 28, 2022
1 parent 7ee6b78 commit ffa3fa3
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions documentation/migration-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ To translate documents like Word files and PDFs, the old `DeepLClient` offered t

The translation options can now be specified via the `DocumentTranslateOptions` class, that can optionally be passed to `TranslateDocumentAsync` as argument. The `DocumentTranslateOptions` can be used to specify the formality of the translation and the glossary that is to be used. In the old `DeepLClient`, the formality could directly be specified in the `TranslateDocumentAsync` methods using the `formality` parameter.

Just as the old `TranslateDocumentAsync` method handled the upload, the wait until the translation is complete, and the download of the translated document for you, so does the the new `TranslateDocumentAsync` method. If, however, your application requires you to perform these steps manually, the old `DeepLClient` offered you the `UploadDocumentForTranslationAsync`, `CheckTranslationStatusAsync`, and `DownloadTranslatedDocumentAsync` methods. `UploadDocumentForTranslationAsync` uploaded the document file to the DeepL API and requested its translation. `CheckTranslationStatusAsync`, checked the status of the translation, i.e., whether the translation has finished yet and if not how many seconds are left. After the translation has finished, the `DownloadTranslatedDocumentAsync` method, downloaded the translated document from the DeepL API. The new .NET binding for DeepL also provides this functionality using the methods `TranslateDocumentUploadAsync`, for uploaded the document and requesting its translation, `TranslateDocumentStatusAsync` for checking the translation status, and `TranslateDocumentDownloadAsync` for downloading the translated document. Furthermore, they also offer another convenience method, `TranslateDocumentWaitUntilDoneAsync`, which continuously checks the translation status of your document asynchronously and returns once the translation has finished (or an error occurred). The `TranslateDocumentUploadAsync` works just like the `TranslateDocumentAsync` method (without having to specify an output stream or an output `FileInfo` object), but it returns right after uploading and requesting the translation. It returns a `DocumentHandle` object, which contains the ID of the document (via the `DocumentId` property) and the key for associated with the document translation (via the `DocumentKey`). The document key is a unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. The `DocumentHandle` class is equivalent to the old `DocumentTranslation` class of the old DeepL .NET binding and the property names are exactly the same. So, in order to migrate you only have to change the name of the type. The `TranslateDocumentStatusAsync` requires you to pass the `DocumentHandle` object received from the `TranslateDocumentUploadAsync` and returns a `DocumentStatus` object, which contains the document ID (via the `DocumentId` property), the status (via the `Status` property), the number of seconds remaining until the translation is complete (via the `SecondsRemaining` property), the number of characters that were billed for the translation of the document (via the `BilledCharacters` property), an error message if an error occurred (via the `ErrorMessage` property), and two convenience properties: `Ok` and `Done`, which evaluate to `true` if no error occurred and if the translation has finished, respectively. The status is of type `StatusCode`, which is an enumeration that has the values `Queued`, `Translating`, `Done`, and `Error`. These are exactly the same names as in the old `TranslationState` enumeration, which was returned by the `CheckTranslationStatusAsync` method, so you only have to change the enumeration type name from `TranslationState` to `StatusCode`.The `TranslateDocumentWaitUntilDoneAsync` works just like the `TranslateDocumentStatusAsync` method, but instead of returning the current translation status it returns once the translation has finished. Finally, the `TranslateDocumentDownloadAsync` method takes the `DocumentHandle` object as argument as well as an output stream or an output `FileInfo` object, and downloads the translated document. The following listing shows the old way and the new way of manually translating documents:
Just as the old `TranslateDocumentAsync` method handled the upload, the wait until the translation is complete, and the download of the translated document for you, so does the the new `TranslateDocumentAsync` method. If, however, your application requires you to perform these steps manually, the old `DeepLClient` offered you the `UploadDocumentForTranslationAsync`, `CheckTranslationStatusAsync`, and `DownloadTranslatedDocumentAsync` methods. `UploadDocumentForTranslationAsync` uploaded the document file to the DeepL API and requested its translation. `CheckTranslationStatusAsync`, checked the status of the translation, i.e., whether the translation has finished yet and if not how many seconds are left. After the translation has finished, the `DownloadTranslatedDocumentAsync` method, downloaded the translated document from the DeepL API. The new .NET binding for DeepL also provides this functionality using the methods `TranslateDocumentUploadAsync`, for uploaded the document and requesting its translation, `TranslateDocumentStatusAsync` for checking the translation status, and `TranslateDocumentDownloadAsync` for downloading the translated document. Furthermore, they also offer another convenience method, `TranslateDocumentWaitUntilDoneAsync`, which continuously checks the translation status of your document asynchronously and returns once the translation has finished (or an error occurred). The `TranslateDocumentUploadAsync` works just like the `TranslateDocumentAsync` method (without having to specify an output stream or an output `FileInfo` object), but it returns right after uploading and requesting the translation. It returns a `DocumentHandle` object, which contains the ID of the document (via the `DocumentId` property) and the key associated with the document translation (via the `DocumentKey`). The document key is a unique key that is used to encrypt the uploaded document as well as the resulting translation on the server side. The `DocumentHandle` class is equivalent to the old `DocumentTranslation` class of the old DeepL .NET binding and the property names are exactly the same. So, in order to migrate you only have to change the name of the type. The `TranslateDocumentStatusAsync` requires you to pass the `DocumentHandle` object received from the `TranslateDocumentUploadAsync` and returns a `DocumentStatus` object, which contains the document ID (via the `DocumentId` property), the status (via the `Status` property), the number of seconds remaining until the translation is complete (via the `SecondsRemaining` property), the number of characters that were billed for the translation of the document (via the `BilledCharacters` property), an error message if an error occurred (via the `ErrorMessage` property), and two convenience properties: `Ok` and `Done`, which evaluate to `true` if no error occurred and if the translation has finished, respectively. The status is of type `StatusCode`, which is an enumeration that has the values `Queued`, `Translating`, `Done`, and `Error`. These are exactly the same names as in the old `TranslationState` enumeration, which was returned by the `CheckTranslationStatusAsync` method, so you only have to change the enumeration type name from `TranslationState` to `StatusCode`. The `TranslateDocumentWaitUntilDoneAsync` works just like the `TranslateDocumentStatusAsync` method, but instead of returning the current translation status it returns once the translation has finished. Finally, the `TranslateDocumentDownloadAsync` method takes the `DocumentHandle` object as argument as well as an output stream or an output `FileInfo` object, and downloads the translated document. The following listing shows the old way and the new way of manually translating documents:

```csharp
// Old way
Expand Down Expand Up @@ -155,7 +155,7 @@ catch (Exception exception)

## Listing Available Languages

The old `DeepLClient` class had a method called `GetSupportedLanguagesAsync`, which returned a list of `SupportedLanguage` objects that contain the currently supported languages of the DeepL translation service. Each `SupportedLanguage` object contains the language code (`LanguageCode`) and the name of the language (`Name`). The Supported language objects could directly be used in the `TranslateAsync`, `UploadDocumentForTranslationAsync`, and `TranslateDocumentAsync` methods to specify the source and target language. The problem here was, that some of the language codes retrieved could only be used as target languages and some only as source languages. The new DeepL .NET binding solves this by having two separate methods: `GetSourceLanguagesAsync`, which returns an array of `SourceLanguage` objects, and `GetTargetLanguagesAsync`, which returns an array of `TargetLanguage` objects. The both inherit from `Language`, which contains two public properties: `Name` and `Code`. `Language`, in contrast to the old `SupportedLanguage`, has a lot of convenience methods built-in. For example, it can be implicitly cast to a string, which means, that it can also be directly used in all translation methods, because the compiler will automatically cast the `Language` object to a string. `Language` also implements `IEquatable` and has a property for creating a CultureInfo from the language code.
The old `DeepLClient` class had a method called `GetSupportedLanguagesAsync`, which returned a list of `SupportedLanguage` objects that contain the currently supported languages of the DeepL translation service. Each `SupportedLanguage` object contains the language code (via the `LanguageCode` property) and the name of the language (vie the `Name` property). The `SupportedLanguage` objects could directly be used in the `TranslateAsync`, `UploadDocumentForTranslationAsync`, and `TranslateDocumentAsync` methods to specify the source and target language. The problem here was, that some of the language codes retrieved could only be used as target languages and some only as source languages. The new DeepL .NET binding solves this by having two separate methods: `GetSourceLanguagesAsync`, which returns an array of `SourceLanguage` objects, and `GetTargetLanguagesAsync`, which returns an array of `TargetLanguage` objects. They both inherit from `Language`, which contains two public properties: `Name` and `Code`. `Language`, in contrast to the old `SupportedLanguage`, has a lot of convenience methods built-in. For example, it can be implicitly cast to a string, which means, that it can also be directly used in all translation methods, because the compiler will automatically cast the `Language` object to a string containing the language code. `Language` also implements `IEquatable` and has a property for creating a `CultureInfo` from the language code.

## Monitoring Usage

Expand Down

0 comments on commit ffa3fa3

Please sign in to comment.