Google Cloud Translation v2 API - Class TranslationClient (3.3.0)

public abstract class TranslationClient : IDisposable

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

Abstract class providing operations for Google Cloud Translation.

Inheritance

object > TranslationClient

Implements

IDisposable

Derived Types

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, TranslationModel), CreateAsync(GoogleCredential, TranslationModel) and CreateFromApiKey(string, TranslationModel) to construct instances; alternatively, you can construct a TranslationClientImpl 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 TranslationClientImpl.

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

Properties

DefaultModel

public virtual TranslationModel DefaultModel { get; }

The default translation model used by this client.

Property Value
TypeDescription
TranslationModel
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 TranslationClient 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 TranslationClient Create()

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

Returns
TypeDescription
TranslationClient

Create(GoogleCredential, TranslationModel)

public static TranslationClient Create(GoogleCredential credential = null, TranslationModel model = TranslationModel.ServiceDefault)

Synchronously creates a TranslationClient, 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 TranslationClientBuilder and set the Credential property.

modelTranslationModel

The default translation model to use. Defaults to ServiceDefault.

Returns
TypeDescription
TranslationClient

The created TranslationClient.

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 TranslationClientBuilder and set the Credential property.

CreateAsync()

public static Task<TranslationClient> CreateAsync()

Asynchronously creates a TranslationClient using application default credentials. For any non-default values, please use TranslationClientBuilder.

Returns
TypeDescription
TaskTranslationClient

The task representing the created TranslationClient.

CreateAsync(GoogleCredential, TranslationModel)

public static Task<TranslationClient> CreateAsync(GoogleCredential credential = null, TranslationModel model = TranslationModel.ServiceDefault)

Asynchronously creates a TranslationClient, 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 TranslationClientBuilder and set the Credential property.

modelTranslationModel

The default translation model to use. Defaults to ServiceDefault.

Returns
TypeDescription
TaskTranslationClient

The task representing the created TranslationClient.

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 TranslationClientBuilder and set the Credential property.

CreateFromApiKey(string, TranslationModel)

public static TranslationClient CreateFromApiKey(string apiKey, TranslationModel model = TranslationModel.ServiceDefault)

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

Parameters
NameDescription
apiKeystring

API key to use. Must not be null.

modelTranslationModel

The default translation model to use. Defaults to ServiceDefault.

Returns
TypeDescription
TranslationClient

The created TranslationClient.

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
TranslationClient client = TranslationClient.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
TranslationClient client = TranslationClient.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
TranslationClient client = TranslationClient.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
TranslationClient client = TranslationClient.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 TranslationClient remarks on when this should be called.

ListLanguages(string, TranslationModel?)

public virtual IList<Language> ListLanguages(string target = null, TranslationModel? 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.

modelTranslationModel

The model to request languages for. May be null, in which case DefaultModel is used.

Returns
TypeDescription
IListLanguage

A list of supported languages.

Example
TranslationClient client = TranslationClient.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, TranslationModel?, CancellationToken)

public virtual Task<IList<Language>> ListLanguagesAsync(string target = null, TranslationModel? 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.

modelTranslationModel

The model to request languages for. May be null, in which case DefaultModel is used.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskIListLanguage

A list of supported languages.

Example
TranslationClient client = await TranslationClient.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, TranslationModel?)

public virtual IList<TranslationResult> TranslateHtml(IEnumerable<string> htmlItems, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

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
TranslationClient client = TranslationClient.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, TranslationModel?)

public virtual TranslationResult TranslateHtml(string html, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

Returns
TypeDescription
TranslationResult

The translation of html.

Remarks

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

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

Example
TranslationClient client = TranslationClient.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, TranslationModel?, CancellationToken)

public virtual Task<IList<TranslationResult>> TranslateHtmlAsync(IEnumerable<string> htmlItems, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

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, TranslationModel?, CancellationToken)

public virtual Task<TranslationResult> TranslateHtmlAsync(string html, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

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, TranslationModel?, CancellationToken)

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

Example
TranslationClient client = await TranslationClient.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, TranslationModel?)

public virtual IList<TranslationResult> TranslateText(IEnumerable<string> textItems, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

Returns
TypeDescription
IListTranslationResult

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

Example
TranslationClient client = TranslationClient.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, TranslationModel?)

public virtual TranslationResult TranslateText(string text, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

Returns
TypeDescription
TranslationResult

The translation of text.

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

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

public virtual Task<IList<TranslationResult>> TranslateTextAsync(IEnumerable<string> textItems, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

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, TranslationModel?, CancellationToken)

public virtual Task<TranslationResult> TranslateTextAsync(string text, string targetLanguage, string sourceLanguage = null, TranslationModel? 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.

modelTranslationModel

The model to request for translation. May be null, in which case DefaultModel is used.

cancellationTokenCancellationToken

The token to monitor for cancellation requests.

Returns
TypeDescription
TaskTranslationResult

The translation of text.

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