Google Cloud Translation v2 API - Class AdvancedTranslationClient (3.2.0-beta01)

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

Inherited Members

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ToString()

Derived Types

AdvancedTranslationClientImpl

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
Type	Description
`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
Type	Description
`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
Type	Description
`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
Name	Description
`credential`	`GoogleCredential` 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.
`model`	`String` The default translation model to use. Defaults to null, indicating that by default no model is specified in requests.

Returns
Type	Description
`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
Type	Description
`Task<AdvancedTranslationClient>`	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
Name	Description
`credential`	`GoogleCredential` 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.
`model`	`String` The default translation model to use. Defaults to null, indicating that by default no model is specified in requests.

Returns
Type	Description
`Task<AdvancedTranslationClient>`	The task representing the created AdvancedTranslationClient.

Remarks

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
Name	Description
`apiKey`	`String` API key to use. Must not be null.
`model`	`String` The default translation model to use. Defaults to null, indicating that by default no model is specified in requests.

Returns
Type	Description
`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
Name	Description
`text`	`String` The text to detect the language of. Must not be null.

Returns
Type	Description
`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 async Task<Detection> DetectLanguageAsync(string text, CancellationToken cancellationToken = default(CancellationToken))

Detects the language of the specified text asynchronously.

Parameters
Name	Description
`text`	`String` The text to detect the language of. Must not be null.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests.

Returns
Type	Description
`Task<Detection>`	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
Name	Description
`textItems`	`IEnumerable<String>` The text items to detect the language of. Must not be null or contain null elements.

Returns
Type	Description
`IList<Detection>`	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(CancellationToken))

Detects the languages of the specified text items asynchronously.

Parameters
Name	Description
`textItems`	`IEnumerable<String>` The text items to detect the language of. Must not be null or contain null elements.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests.

Returns
Type	Description
`Task<IList<Detection>>`	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
Name	Description
`target`	`String` 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.
`model`	`String` 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
Type	Description
`IList<Language>`	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(CancellationToken))

Lists the language supported by the Translate API asynchronously.

Parameters
Name	Description
`target`	`String` 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.
`model`	`String` 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.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests.

Returns
Type	Description
`Task<IList<Language>>`	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
Name	Description
`htmlItems`	`IEnumerable<String>` The HTML strings to translate. Must not be null or contain null elements.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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
Type	Description
`IList<TranslationResult>`	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
Name	Description
`html`	`String` The HTML to translate.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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
Type	Description
`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(CancellationToken))

Translates multiple items of HTML asynchronously.

Parameters
Name	Description
`htmlItems`	`IEnumerable<String>` The HTML strings to translate. Must not be null or contain null elements.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests.

Returns
Type	Description
`Task<IList<TranslationResult>>`	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 async Task<TranslationResult> TranslateHtmlAsync(string html, string targetLanguage, string sourceLanguage = null, string model = null, CancellationToken cancellationToken = default(CancellationToken))

Translates a single item of HTML asynchronously.

Parameters
Name	Description
`html`	`String` The HTML to translate. Must not be null.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests.

Returns
Type	Description
`Task<TranslationResult>`	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
Name	Description
`textItems`	`IEnumerable<String>` The text strings to translate. Must not be null or contain null elements.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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
Type	Description
`IList<TranslationResult>`	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
Name	Description
`text`	`String` The text to translate.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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
Type	Description
`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(CancellationToken))

Translates multiple items of text asynchronously.

Parameters
Name	Description
`textItems`	`IEnumerable<String>` The text strings to translate. Must not be null or contain null elements.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests.

Returns
Type	Description
`Task<IList<TranslationResult>>`	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 async Task<TranslationResult> TranslateTextAsync(string text, string targetLanguage, string sourceLanguage = null, string model = null, CancellationToken cancellationToken = default(CancellationToken))

Translates a single item of text asynchronously.

Parameters
Name	Description
`text`	`String` The text to translate. Must not be null.
`targetLanguage`	`String` The code for the language to translate into. Must not be null.
`sourceLanguage`	`String` The code for the language to translate from. May be null, in which case the server will detect the source language.
`model`	`String` 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.
`cancellationToken`	`CancellationToken` The token to monitor for cancellation requests.

Returns
Type	Description
`Task<TranslationResult>`	The translation of `text`.

Remarks

This implementation simply delegates to TranslateTextAsync(IEnumerable<String>, String, String, String, CancellationToken)

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}");