Google Cloud Translation v2 API - Class AdvancedTranslationClient (3.3.0)

public abstract class AdvancedTranslationClient : IDisposable

Reference documentation and code samples for the Google Cloud Translation v2 API class AdvancedTranslationClient.

Abstract class providing operations for Google Cloud Translation. This class uses strings for model names, unlike TranslationClient which uses the TranslationModel enum. This makes it less convenient to use for simple cases, but more powerful in allowing arbitrary custom models to be specified.

Inheritance

object > AdvancedTranslationClient

Implements

IDisposable

Namespace

Google.Cloud.Translation.V2

Assembly

Google.Cloud.Translation.V2.dll

Remarks

This abstract class is provided to enable testability while permitting additional operations to be added in the future. See Create(GoogleCredential, string), CreateAsync(GoogleCredential, string) and CreateFromApiKey(string, string) to construct instances; alternatively, you can construct a AdvancedTranslationClientImpl directly from a TranslateService.

All instance methods declared in this class are virtual, with an implementation which simply throws NotImplementedException. All these methods are overridden in AdvancedTranslationClientImpl.

This class implements IDisposable; however, the Dispose() method only requires calling if many short-lived instances of AdvancedTranslationClient are being created. Most code would be expected to create a single AdvancedTranslationClient instance, and use this instance throughout the lifetime of the application. In this case, Dispose need not be called.

Properties

DefaultModel

public virtual string DefaultModel { get; }

The default translation model used by this client.

Property Value
TypeDescription
string
Remarks

Each Translate method has an optional parameter to override this.

Service

public virtual TranslateService Service { get; }

The underlying translation service object used by this client.

Property Value
TypeDescription
TranslateService
Remarks

The AdvancedTranslationClient class only provides convenience operations built on top of an existing service object. Any more complex operations which are not supported by this wrapper may wish to use the same service object as the wrapper, in order to take advantage of its configuration (for authentication, application naming etc).

Methods

Create()

public static AdvancedTranslationClient Create()

Synchronously creates a nAdvancedTranslationClient using application default credentials. For any non-default values, please use AdvancedTranslationClientBuilder.

Returns
TypeDescription
AdvancedTranslationClient

Create(GoogleCredential, string)

public static AdvancedTranslationClient Create(GoogleCredential credential = null, string model = null)

Synchronously creates a AdvancedTranslationClient, using application default credentials if no credentials are specified.

Parameters
NameDescription
credentialGoogleCredential

Optional GoogleCredential. If this is non-null, default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a AdvancedTranslationClientBuilder and set the Credential property.

modelstring

The default translation model to use. Defaults to null, indicating that by default no model is specified in requests.

Returns
TypeDescription
AdvancedTranslationClient

The created AdvancedTranslationClient.

Remarks

If a credential is supplied, the default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a AdvancedTranslationClientBuilder and set the Credential property.

CreateAsync()

public static Task<AdvancedTranslationClient> CreateAsync()

Asynchronously creates an AdvancedTranslationClient using application default credentials. For any non-default values, please use AdvancedTranslationClientBuilder.

Returns
TypeDescription
TaskAdvancedTranslationClient

The task representing the created AdvancedTranslationClient.

CreateAsync(GoogleCredential, string)

public static Task<AdvancedTranslationClient> CreateAsync(GoogleCredential credential = null, string model = null)

Asynchronously creates a AdvancedTranslationClient, using application default credentials if no credentials are specified.

Parameters
NameDescription
credentialGoogleCredential

Optional GoogleCredential. If this is non-null, default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a AdvancedTranslationClientBuilder and set the Credential property.

modelstring

The default translation model to use. Defaults to null, indicating that by default no model is specified in requests.

Returns
TypeDescription
TaskAdvancedTranslationClient

The task representing the created AdvancedTranslationClient.

Remarks

If a credential is supplied, the default scopes are applied to it (for credential types that support scoping), overriding any existing scopes in the credentials. To use scoped credentials without any modifications, create a AdvancedTranslationClientBuilder and set the Credential property.

CreateFromApiKey(string, string)

public static AdvancedTranslationClient CreateFromApiKey(string apiKey, string model = null)

Creates a AdvancedTranslationClient from an API key instead of using OAuth2 credentials.

Parameters
NameDescription
apiKeystring

API key to use. Must not be null.

modelstring

The default translation model to use. Defaults to null, indicating that by default no model is specified in requests.

Returns
TypeDescription
AdvancedTranslationClient

The created AdvancedTranslationClient.

Remarks

You are encouraged to use OAuth2 credentials where possible. This method is primarily provided to make the transition from using API keys to OAuth2 credentials straightforward.

DetectLanguage(string)

public virtual Detection DetectLanguage(string text)

Detects the language of the specified text synchronously.

Parameter
NameDescription
textstring

The text to detect the language of. Must not be null.

Returns
TypeDescription
Detection

The most likely detected language.

Remarks

This implementation simply delegates to DetectLanguages(IEnumerable<string>).

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
Detection result = client.DetectLanguage("It is raining.");
Console.WriteLine($"Language: {result.Language}; confidence {result.Confidence}");

DetectLanguageAsync(string, CancellationToken)

public virtual Task<Detection> DetectLanguageAsync(string text, CancellationToken cancellationToken = default)

Detects the language of the specified text asynchronously.

Parameters
NameDescription
textstring

The text to detect the language of. Must not be null.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskDetection

The most likely detected language.

Remarks

This implementation simply delegates to DetectLanguagesAsync(IEnumerable<string>, CancellationToken).

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
Detection result = await client.DetectLanguageAsync("It is raining.");
Console.WriteLine($"Language: {result.Language}; confidence {result.Confidence}");

DetectLanguages(IEnumerable<string>)

public virtual IList<Detection> DetectLanguages(IEnumerable<string> textItems)

Detects the languages of the specified text items synchronously.

Parameter
NameDescription
textItemsIEnumerablestring

The text items to detect the language of. Must not be null or contain null elements.

Returns
TypeDescription
IListDetection

A list of detected languages. This will be the same size as textItems, in the same order.

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
IList<Detection> results = client.DetectLanguages(new[] { "It is raining.", RainingTranslation });
foreach (var result in results)
{
    Console.WriteLine($"Text: {result.Text}; language: {result.Language}; confidence {result.Confidence}");
}

DetectLanguagesAsync(IEnumerable<string>, CancellationToken)

public virtual Task<IList<Detection>> DetectLanguagesAsync(IEnumerable<string> textItems, CancellationToken cancellationToken = default)

Detects the languages of the specified text items asynchronously.

Parameters
NameDescription
textItemsIEnumerablestring

The text items to detect the language of. Must not be null or contain null elements.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskIListDetection

A list of detected languages. This will be the same size as textItems, in the same order.

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
IList<Detection> results = await client.DetectLanguagesAsync(new[] { "It is raining.", RainingTranslation });
foreach (var result in results)
{
    Console.WriteLine($"Text: {result.Text}; language: {result.Language}; confidence {result.Confidence}");
}

Dispose()

public virtual void Dispose()

Dispose of this instance. See the AdvancedTranslationClient remarks on when this should be called.

ListLanguages(string, string)

public virtual IList<Language> ListLanguages(string target = null, string model = null)

Lists the language supported by the Translate API synchronously.

Parameters
NameDescription
targetstring

The target language in which to return the language names in the results, for display purposes. May be null, in which case only the language codes are returned.

modelstring

The model to request languages for. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

Returns
TypeDescription
IListLanguage

A list of supported languages.

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
IList<Language> languages = client.ListLanguages(LanguageCodes.English);
// Display just the first 10 languages for brevity
foreach (Language language in languages.Take(10))
{
    Console.WriteLine($"Language: {language.Name}; code {language.Code}");
}

ListLanguagesAsync(string, string, CancellationToken)

public virtual Task<IList<Language>> ListLanguagesAsync(string target = null, string model = null, CancellationToken cancellationToken = default)

Lists the language supported by the Translate API asynchronously.

Parameters
NameDescription
targetstring

The target language in which to return the language names in the results, for display purposes. May be null, in which case only the language codes are returned.

modelstring

The model to request languages for. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskIListLanguage

A list of supported languages.

Example
AdvancedTranslationClient client = await AdvancedTranslationClient.CreateAsync();
IList<Language> languages = await client.ListLanguagesAsync(LanguageCodes.English);
// Display just the first 10 languages for brevity
foreach (Language language in languages.Take(10))
{
    Console.WriteLine($"Language: {language.Name}; code {language.Code}");
}

TranslateHtml(IEnumerable<string>, string, string, string)

public virtual IList<TranslationResult> TranslateHtml(IEnumerable<string> htmlItems, string targetLanguage, string sourceLanguage = null, string model = null)

Translates multiple items of HTML synchronously.

Parameters
NameDescription
htmlItemsIEnumerablestring

The HTML strings to translate. Must not be null or contain null elements.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

Returns
TypeDescription
IListTranslationResult

A list of translations. This will be the same size as htmlItems, in the same order.

Remarks

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
IList<TranslationResult> results = client.TranslateHtml(
    new[] { "<p><strong>It is raining.</strong></p>", "<p><strong>It is sunny.</strong></p>" },
    LanguageCodes.French);
foreach (TranslationResult result in results)
{
    Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");
}

TranslateHtml(string, string, string, string)

public virtual TranslationResult TranslateHtml(string html, string targetLanguage, string sourceLanguage = null, string model = null)

Translates a single item of HTML synchronously.

Parameters
NameDescription
htmlstring

The HTML to translate.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

Returns
TypeDescription
TranslationResult

The translation of html.

Remarks

This implementation simply delegates to TranslateHtml(IEnumerable<string>, string, string, string)

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
TranslationResult result = client.TranslateHtml("<p><strong>It is raining.</strong></p>", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");

TranslateHtmlAsync(IEnumerable<string>, string, string, string, CancellationToken)

public virtual Task<IList<TranslationResult>> TranslateHtmlAsync(IEnumerable<string> htmlItems, string targetLanguage, string sourceLanguage = null, string model = null, CancellationToken cancellationToken = default)

Translates multiple items of HTML asynchronously.

Parameters
NameDescription
htmlItemsIEnumerablestring

The HTML strings to translate. Must not be null or contain null elements.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskIListTranslationResult

A list of translations. This will be the same size as htmlItems, in the same order.

Remarks

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example

See TranslateHtmlAsync for an example using an alternative overload.

TranslateHtmlAsync(string, string, string, string, CancellationToken)

public virtual Task<TranslationResult> TranslateHtmlAsync(string html, string targetLanguage, string sourceLanguage = null, string model = null, CancellationToken cancellationToken = default)

Translates a single item of HTML asynchronously.

Parameters
NameDescription
htmlstring

The HTML to translate. Must not be null.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskTranslationResult

The translation of html.

Remarks

This implementation simply delegates to TranslateHtmlAsync(IEnumerable<string>, string, string, string, CancellationToken)

See the Translation API documentation for more details on how to translate HTML and the terms of service.

Example
AdvancedTranslationClient client = await AdvancedTranslationClient.CreateAsync();
TranslationResult result = await client.TranslateHtmlAsync("<p><strong>It is raining.</strong></p>", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");

TranslateText(IEnumerable<string>, string, string, string)

public virtual IList<TranslationResult> TranslateText(IEnumerable<string> textItems, string targetLanguage, string sourceLanguage = null, string model = null)

Translates multiple items of text synchronously.

Parameters
NameDescription
textItemsIEnumerablestring

The text strings to translate. Must not be null or contain null elements.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

Returns
TypeDescription
IListTranslationResult

A list of translations. This will be the same size as textItems, in the same order.

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
IList<TranslationResult> results = client.TranslateText(
    new[] { "It is raining.", "It is sunny." },
    LanguageCodes.French);
foreach (TranslationResult result in results)
{
    Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");
}

TranslateText(string, string, string, string)

public virtual TranslationResult TranslateText(string text, string targetLanguage, string sourceLanguage = null, string model = null)

Translates a single item of text synchronously.

Parameters
NameDescription
textstring

The text to translate.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

Returns
TypeDescription
TranslationResult

The translation of text.

Remarks

This implementation simply delegates to TranslateText(IEnumerable<string>, string, string, string)

Example
AdvancedTranslationClient client = AdvancedTranslationClient.Create();
TranslationResult result = client.TranslateText("It is raining.", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");

TranslateTextAsync(IEnumerable<string>, string, string, string, CancellationToken)

public virtual Task<IList<TranslationResult>> TranslateTextAsync(IEnumerable<string> textItems, string targetLanguage, string sourceLanguage = null, string model = null, CancellationToken cancellationToken = default)

Translates multiple items of text asynchronously.

Parameters
NameDescription
textItemsIEnumerablestring

The text strings to translate. Must not be null or contain null elements.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskIListTranslationResult

A list of translations. This will be the same size as textItems, in the same order.

Example

See TranslateTextAsync for an example using an alternative overload.

TranslateTextAsync(string, string, string, string, CancellationToken)

public virtual Task<TranslationResult> TranslateTextAsync(string text, string targetLanguage, string sourceLanguage = null, string model = null, CancellationToken cancellationToken = default)

Translates a single item of text asynchronously.

Parameters
NameDescription
textstring

The text to translate. Must not be null.

targetLanguagestring

The code for the language to translate into. Must not be null.

sourceLanguagestring

The code for the language to translate from. May be null, in which case the server will detect the source language.

modelstring

The model to request for translation. May be null, in which case DefaultModel is used. If the empty string is specified, no model is requested, allowing the server to choose.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskTranslationResult

The translation of text.

Remarks Example
AdvancedTranslationClient client = await AdvancedTranslationClient.CreateAsync();
TranslationResult result = await client.TranslateTextAsync("It is raining.", LanguageCodes.French);
Console.WriteLine($"Result: {result.TranslatedText}; detected language {result.DetectedSourceLanguage}");